Skip to navigation Skip to main content
Blog
Eleventy, 2024 in Review
Versions
Stable
3.0.0
Beta
3.1.0-beta.1

Programmatic API

On this page

You can run Eleventy in any arbitrary Node script.

Write to the file system

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

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

my-node-script.js
import Eleventy from "@11ty/eleventy";

let elev = new Eleventy();
await elev.write();
(async function () {
	const { Eleventy } = await import("@11ty/eleventy");

	let elev = new Eleventy();
	await elev.write();
})();

Then run your new script from the command line. Don’t include ~ $ when you run this command.

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() or .toNDJSON().

JSON Output

my-node-script.js
import Eleventy from "@11ty/eleventy";

let elev = new Eleventy();
let json = await elev.toJSON();

// All results
console.log(json);
(async function () {
	const { Eleventy } = await import("@11ty/eleventy");

	let elev = new Eleventy();
	let json = await elev.toJSON();

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

Adding data to JSON output

You can use the eleventyConfig.dataFilterSelectors configuration API Set 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 Eleventy from "@11ty/eleventy";

let elev = new Eleventy(".", "_site", {
	config: function(eleventyConfig) {
		eleventyConfig.dataFilterSelectors.add("globalData.key1");
		eleventyConfig.dataFilterSelectors.add("globalData.key2");
		eleventyConfig.dataFilterSelectors.add("someProperty.key");
	}
});

let json = await elev.toJSON();

// All results with
// json[…].data.globalData.key1
// json[…].data.globalData.key2
// json[…].data.someProperty.key
console.log(json);
(async function () {
	const { Eleventy } = await import("@11ty/eleventy");

	let elev = new Eleventy(".", "_site", {
		config: function(eleventyConfig) {
			eleventyConfig.dataFilterSelectors.add("globalData.key1");
			eleventyConfig.dataFilterSelectors.add("globalData.key2");
			eleventyConfig.dataFilterSelectors.add("someProperty.key");
		}
	});

	let json = await elev.toJSON();

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

ndjson Output

my-node-script.js
import Eleventy from "@11ty/eleventy";

let elev = new Eleventy();
let stream = await elev.toNDJSON();
stream.on("data", (entry) => {
	// Stream one output result at a time
	let json = JSON.parse(entry.toString());
	console.log(json);
});
(async function () {
	const { Eleventy } = await import("@11ty/eleventy");

	let elev = new Eleventy();
	let stream = await elev.toNDJSON();
	stream.on("data", (entry) => {
		// Stream one output result at a time
		let json = JSON.parse(entry.toString());
		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 Eleventy from "@11ty/eleventy";

let elev = new Eleventy(".", "_site");

// Use `write` or `toJSON` or `toNDJSON`
(async function () {
	const { Eleventy } = await import("@11ty/eleventy");

	let elev = new Eleventy(".", "_site");

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

Full Options List

The third argument to Eleventy is an options object.

(This documentation section is a work in progress but you’re welcome to dig into the Eleventy class source code in v3.0.0 to learn more)

my-node-script.js
import Eleventy from "@11ty/eleventy";

let elev = new Eleventy(".", "_site", {
	// --quiet
	quietMode: true,

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

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

// Use `write` or `toJSON` or `toNDJSON`
(async function () {
	const { Eleventy } = await import("@11ty/eleventy");

	let elev = new Eleventy(".", "_site", {
		// --quiet
		quietMode: true,

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

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

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

Other pages in Advanced