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

Instead of running Build Awesome from the command line, you can import it and run it from any Node script — useful for custom build tooling, running Build Awesome as part of a larger process, or retrieving your rendered content as data without writing any files.

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

Simplest

The constructor takes an options object and every property is optional.

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

let ba = new BuildAwesome({
	input: ".",				// optional
	output: "_site",	// optional
});

await ba.write();

const { default: BuildAwesome } = require("@awesome.me/buildawesome");

(async function () {
	let ba = new BuildAwesome({
		input: ".",				// optional
		output: "_site",	// optional
	});

	await ba.write();
})();

Then run your new script from the command line.

node my-node-script.js

write() is one of a few build methods offered (toJSON() is also commonly used).

Options

All configuration is passed through an options object and every property is optional.

Option Type Default Description
input string "." The input directory (or a single input file). Mirrors the --input CLI flag.
output string "_site" The output directory. Mirrors the --output CLI flag.
configPath string (none) Path to a configuration file. Equivalent to the --config CLI flag.
config function (none) A configuration callback that receives the config API object.
quietMode boolean false When true, suppresses the build output logging. Equivalent to the --quiet CLI flag.
dryRun boolean false When true, runs a full build but does not write anything to the file system.
runMode string "build" One of "build", "watch", or "serve".
pathPrefix string "/" Prepends this value to all URLs. Equivalent to the --pathprefix CLI option used with the HTML <base> plugin.
loader string "auto" Force the module mode: "esm", "cjs", or "auto" (detected from your package.json type).
my-node-script.js
import BuildAwesome from "@awesome.me/buildawesome";

let ba = new BuildAwesome({
	// Input and output directories
	input: ".",
	output: "_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`

const { default: BuildAwesome } = require("@awesome.me/buildawesome");

(async function () {
	let ba = new BuildAwesome({
		// Input and output directories
		input: ".",
		output: "_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`
})();
Backwards compatibility note
In previous versions, input and output were passed in as separate arguments (e.g. new BuildAwesome(input, output, options)). Starting with Build Awesome v4, the single options argument is now recommended. Feel free to browse the v3 documentation for more information.

The config Callback

The config option is a function that receives the Configuration API object, letting you configure Build Awesome inline without a separate config file:

Notably, the config callback does not replace your configuration file: both run. Importantly, they run in this order:

  1. config callback function
  2. configPath configuration file (can override things set in config)

Building Your Project

Making a new instance of Build Awesome doesn’t process anything: you must call one of these methods to execute a build. Each returns a Promise, so use with await or .then().

Method Returns Description
write() Promise<Array> Renders and writes output to the file system.
toJSON() Promise<Array> Renders and returns output as data (no files written).
watch() Promise Runs an initial build, then rebuilds on file changes.
serve(port) Promise Starts the Dev Server on the given port.

Write to the File System

Use write() to render your site and write the output files to the output directory—this is the same thing running Build Awesome from the command line does.

Don’t Write to the File System

If you want to retrieve the rendered content programmatically without writing anything to disk, use toJSON() (or the dryRun option documented above).

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

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

// All results
console.log(json);

const { default: BuildAwesome } = require("@awesome.me/buildawesome");

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

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

toJSON() resolves to an array of entries, one per rendered output. Each entry includes:

Property Description
inputPath The template’s source path.
outputPath Where the file would be written on disk.
url The output URL for the page.
content The final rendered content.
rawInput The template’s raw (unrendered) input.
data Selected Data Cascade entries—only present when you add data filter selectors.

Adding data to JSON output

By default, the data property is not included in toJSON entries. Use the $config.dataFilterSelectors configuration API Set instance to add (or remove) lodash-style selectors for the Data Cascade entries you want included:

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

let ba = new BuildAwesome({
	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);

const { default: BuildAwesome } = require("@awesome.me/buildawesome");

(async function () {
	let ba = new BuildAwesome({
		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);
})();

Advanced

Setup Methods

In addition to the constructor options, you can configure an instance by calling these methods before a build. Each corresponds to a command line flag.

Method Description
setFormats(formats) Comma-separated template formats (--formats) to process.
disableLogger() Disable Build Awesome’s logging entirely.

Handling Errors

Wrap your build in a try/catch to handle errors yourself. When run programmatically (source: "script", the default), Build Awesome throws on error rather than changing the process exit code, so it won’t exit your script for you.

Full Options and Source

(This documentation covers the most common options. For everything else, dig into the Core class source code.)

Other pages in Advanced