Events

Lume has an events system to run some code at certain times during the compiling process. You can configure those events in the _config.js file with the function addEventListener.

beforeBuild

This event is triggered just before the site build starts. Note that if you are watching the files with lume --serve, this is only executed once before the initial build. Use beforeUpdate for subsequent changes.

site.addEventListener("beforeBuild", () => {
  console.log("The build is about to start");
});

Note: if the event listener returns false, the build process is stopped:

site.addEventListener("beforeBuild", () => {
  return false; // Stop the build
});

afterBuild

This event is triggered after building the site. Note that if you are watching the files with lume --serve, this is only executed once after the initial build. Use afterUpdate for subsequent changes.

site.addEventListener("afterBuild", (event) => {
  console.log("The build is finished");
  console.log(event.pages); // The pages that have been build
  console.log(event.staticFiles); // The files that have been copied
});

beforeUpdate

This event is triggered every time a change is detected on building the site with lume --serve.

site.addEventListener("beforeUpdate", (event) => {
  console.log("New changes detected");
  console.log(event.files); // The files that have changed
});

Note: if the event listener returns false, the update process is stopped:

site.addEventListener("beforeUpdate", () => {
  return false; // Stop the update
});

afterUpdate

This event is triggered after re-building the site after detecting changes with lume --serve.

site.addEventListener("afterUpdate", (event) => {
  console.log("Site updated");
  console.log(event.files); // The files that have changed
  console.log(event.pages); // The pages that have been rebuilt
  console.log(event.staticFiles); // The static files that have been copied again
});

afterLoad

Event triggered after all files in the source folder are loaded (but not processed). It allows to do low-level operations like renaming files, etc.

beforeRender

This event is triggered just after all pages are loaded but before they are rendered.

site.addEventListener("beforeRender", (event) => {
  console.log("Ready to render the pages");
  console.log(event.pages); // The pages to render
});

afterRender

This event is triggered just after all pages are rendered but before they are processed.

site.addEventListener("afterRender", () => {
  console.log("All pages rendered");
});

beforeSave

This event is triggered just before saving the generated pages.

site.addEventListener("beforeSave", () => {
  console.log("All pages are about to be saved");
});

Note: if the event listener returns false, the save process is stopped:

site.addEventListener("beforeSave", () => {
  return false; // Don't save the files
});

afterStartServer

This event is triggered after starting the local server (with lume --server command).

site.addEventListener("afterStartServer", () => {
  console.log("Local server started successfully");
});

Execute scripts with events

In addition to functions, you can also execute scripts in events by passing a string with the script name.

// Create the script
site.script("compress", "gzip -r _site site.gz");

// Execute it after build the site
site.addEventListener("afterBuild", "compress").

// Or you can run any script directly
site.addEventListener("afterBuild", "gzip -r _site site.gz").

Events options

Similar to web APIs the third argument of addEventListener allows customizing the event listener. The available options are:

• once: To run the listener only once and then remove it.
• signal: To provide an AbortSignal to remove the listener at any time.

Example of a listener executed only once:

site.addEventListener("afterUpdate", () => {
  console.log("This is the first update");
}, {
  once: true,
});

Example of signal usage:

const controller = new AbortController();
let times = 0;

site.addEventListener("afterUpdate", () => {
  times++;

  // Remove the listener after 5 times
  if (times === 5) {
    controller.abort();
  }

  console.log(`This is the update ${times}`);
}, {
  signal: controller.signal,
});