Skip to navigation Skip to main content
These docs are for an upcoming version of Build Awesome — take extra care before linking here as URLs may change! Look to the latest stable docs instead (or the full release history).
Versions
Canary
4.0.0-alpha.10
Stable
3.1.6
Pro
Coming Soon

Programmatic API Added in v1.0.0

On this page

You can run Build Awesome in any arbitrary Node script.

Write to the file system

Don’t forget to install Build Awesome into your local project first!

Now create a file called my-node-script.js with the following contents:

my-node-script.js
import BuildAwesome from "@awesome.me/buildawesome";

let ba = new BuildAwesome();
await ba.write();

(async function () {
	const { default: BuildAwesome } = await import("@awesome.me/buildawesome");

	let ba = new BuildAwesome();
	await ba.write();
})();

Then run your new script from the command line.

node my-node-script.js

Don’t write to the file system

Using .write() will write your output to the file system. If, instead, you want to retrieve the content programmatically without writing, use .toJSON().

JSON Output

my-node-script.js
import BuildAwesome from "@awesome.me/buildawesome";

let ba = new BuildAwesome();
let json = await ba.toJSON();

// All results
console.log(json);

(async function () {
	const { default: BuildAwesome } = await import("@awesome.me/buildawesome");

	let ba = new BuildAwesome();
	let json = await ba.toJSON();

	// All results
	console.log(json);
})();

Adding data to JSON output

You can use the $config.dataFilterSelectors configuration API Set instance to add or remove lodash-style selectors for Data Cascade entries to be included in individual entries from the toJSON method.

my-node-script.js
import BuildAwesome from "@awesome.me/buildawesome";

let ba = new BuildAwesome(".", "_site", {
	config: function($config) {
		$config.dataFilterSelectors.add("globalData.key1");
		$config.dataFilterSelectors.add("globalData.key2");
		$config.dataFilterSelectors.add("someProperty.key");
	}
});

let json = await ba.toJSON();

// All results with
// json[…].data.globalData.key1
// json[…].data.globalData.key2
// json[…].data.someProperty.key
console.log(json);

(async function () {
	const { default: BuildAwesome } = await import("@awesome.me/buildawesome");

	let ba = new BuildAwesome(".", "_site", {
		config: function($config) {
			$config.dataFilterSelectors.add("globalData.key1");
			$config.dataFilterSelectors.add("globalData.key2");
			$config.dataFilterSelectors.add("someProperty.key");
		}
	});

	let json = await ba.toJSON();

	// All results with
	// json[…].data.globalData.key1
	// json[…].data.globalData.key2
	// json[…].data.someProperty.key
	console.log(json);
})();

Changing the Input and Output Directories

The first argument is the input directory. The second argument is the output directory.

my-node-script.js
import BuildAwesome from "@awesome.me/buildawesome";

let ba = new BuildAwesome(".", "_site");

// Use `write` or `toJSON`

(async function () {
	const { default: BuildAwesome } = await import("@awesome.me/buildawesome");

	let ba = new BuildAwesome(".", "_site");

	// Use `write` or `toJSON`
})();

Full Options List

The third argument to Build Awesome is an options object.

(This documentation section is a work in progress but you’re welcome to dig into the Core class source code in v4.0.0-alpha.10 to learn more)

my-node-script.js
import BuildAwesome from "@awesome.me/buildawesome";

let ba = new BuildAwesome(".", "_site", {
	// --quiet
	quietMode: true,

	// --config
	configPath: "buildawesome.config.js",

	config: function ($config) {
		// Do some custom Configuration API stuff
		// Works great with $config.addGlobalData
	},
});

// Use `write` or `toJSON`

(async function () {
	const { default: BuildAwesome } = await import("@awesome.me/buildawesome");

	let ba = new BuildAwesome(".", "_site", {
		// --quiet
		quietMode: true,

		// --config
		configPath: "buildawesome.config.js",

		config: function ($config) {
			// Do some custom Configuration API stuff
			// Works great with $config.addGlobalData
		},
	});

	// Use `write` or `toJSON`
})();

Other pages in Advanced