Events

You may want to run some custom JavaScript code in your configuration file at varying times during Eleventy’s build process. Configuration events unlock this ability.

All events are configured in your configuration file, with the code run every time the event triggers.

Asynchronous callback function support added in v1.0.

eleventy.before

• Previously known as the now deprecated beforeBuild event.

The eleventy.before event runs every time Eleventy starts building, so it will run before the start of each stand-alone build, as well as each time building starts as either part of --watch or --serve. To use it, attach the event handler to your Eleventy config:

export default function(eleventyConfig) {
	// Async-friendly in 1.0+
	// Arguments added in 2.0+
	eleventyConfig.on("eleventy.before", async ({ directories, runMode, outputMode }) => {
		// Run me before the build starts
	});
}

module.exports = function(eleventyConfig) {
	// Async-friendly in 1.0+
	// Arguments added in 2.0+
	eleventyConfig.on("eleventy.before", async ({ directories, runMode, outputMode }) => {
		// Run me before the build starts
	});
}

eleventy.after

• Previously known as the now deprecated afterBuild event.

The eleventy.after event runs every time Eleventy finishes building, so it will run after the end of each stand-alone build, as well as each time building ends as either part of --watch or --serve. To use it, attach the event handler to your Eleventy config:

export default function(eleventyConfig) {
	// Async-friendly in 1.0+
	// Arguments added in 2.0+
	eleventyConfig.on(
		"eleventy.after",
		async ({ directories, results, runMode, outputMode }) => {
			// Run me after the build ends
		}
	);
};

module.exports = function(eleventyConfig) {
	// Async-friendly in 1.0+
	// Arguments added in 2.0+
	eleventyConfig.on(
		"eleventy.after",
		async ({ directories, results, runMode, outputMode }) => {
			// Run me after the build ends
		}
	);
};

Event arguments Added in v2.0.0

Eleventy now provides an object with metadata on the build as an argument to the eleventy.before and eleventy.after event callbacks.

export default function(eleventyConfig) {
	eleventyConfig.on("eleventy.before", async ({ directories, runMode, outputMode }) => {
		// Read more below
	});

	eleventyConfig.on(
		"eleventy.after",
		async ({ dir, results, runMode, outputMode }) => {
			// Read more below
		}
	);
};

module.exports = function(eleventyConfig) {
	eleventyConfig.on("eleventy.before", async ({ directories, runMode, outputMode }) => {
		// Read more below
	});

	eleventyConfig.on(
		"eleventy.after",
		async ({ dir, results, runMode, outputMode }) => {
			// Read more below
		}
	);
};

• directories: an object with normalized project directory paths, set in your in your configuration file (or populated with Eleventy defaults).
  • Included properties: input, inputFile, inputGlob, data, includes, layouts, and output. Works best with a named config export in your configuration file.
• dir (deprecated, use directories instead):
  • Included properties: input (default "."), output (default "_site"), includes (default "_includes"), data (default "_data"), and layouts (no default value).
• outputMode: a string representing the value of --to on the command line
  • fs (default)
  • json
  • ndjson
• runMode: a string representing --serve or --watch usage on the command line. One of:
  • build (default)
  • watch
  • serve
• results: only available on eleventy.after. An array with the processed Eleventy output (similar to --to=json output)
  • Individual entries will have: { inputPath, outputPath, url, content }

eleventy.beforeConfig Added in v3.0.0

The eleventy.beforeConfig runs before your configuration is initialized and was added as an escape hatch for folks unable to update their top-level configuration callback to be async (usually due to some limitation in a third-party tool). You probably won’t need this.

// sync configuration callback
module.exports = function (eleventyConfig) {
	// async-friendly event
  eleventyConfig.on("eleventy.beforeConfig", async function (eleventyConfig) {
    const { HtmlBasePlugin } = await import("@11ty/eleventy");
		eleventyConfig.addPlugin(HtmlBasePlugin);
  });
};

eleventy.beforeWatch

The eleventy.beforeWatch event runs before a build only if it's a re-run during --watch or --serve. This means it will not run during the initial build nor during stand-alone builds.

export default function(eleventyConfig) {
	// Async-friendly
	eleventyConfig.on("eleventy.beforeWatch", async (changedFiles) => {
		// Run me before --watch or --serve re-runs
		// changedFiles is an array of files that changed
		// to trigger the watch/serve build
	});
};

module.exports = function(eleventyConfig) {
	// Async-friendly
	eleventyConfig.on("eleventy.beforeWatch", async (changedFiles) => {
		// Run me before --watch or --serve re-runs
		// changedFiles is an array of files that changed
		// to trigger the watch/serve build
	});
};

eleventy.contentMap Added in v2.0.0

This event facilitates the i18n plugin (but is available independent of it).

export default function(eleventyConfig) {
	// Async-friendly
	eleventyConfig.on("eleventy.contentMap", async ({ inputPathToUrl, urlToInputPath }) => {
		// inputPathToUrl is an object mapping input file paths to output URLs
		// urlToInputPath is an object mapping output URLs to input file paths
	});
};

module.exports = function(eleventyConfig) {
	// Async-friendly
	eleventyConfig.on("eleventy.contentMap", async ({ inputPathToUrl, urlToInputPath }) => {
		// inputPathToUrl is an object mapping input file paths to output URLs
		// urlToInputPath is an object mapping output URLs to input file paths
	});
};

Emitter Modes

Currently Eleventy triggers event callbacks in parallel. If you need to run the event callbacks sequentially, you can do so with the setEventEmitterMode configuration API method. Related GitHub #3415.

export default function(eleventyConfig){
	eleventyConfig.setEventEmitterMode("sequential");
}

module.exports = function(eleventyConfig){
	eleventyConfig.setEventEmitterMode("sequential");
}

Other pages in Advanced

• Release History
• Programmatic API
• Configuration Events
• Order of Operations