eleventy-plugin-clean

This is an experimental plugin for Eleventy to keep the output directory clean.

The plugin does not delete any files not created by Eleventy. It deletes all the files, previously created by Eleventy but no longer created/updated, in the output directory.

⚠️ Don't use weird input and output directories setup even if the official doc recommends, such as https://www.11ty.dev/docs/usage/#using-the-same-input-and-output.

Installation

For Eleventy 3.x

npm install eleventy-plugin-clean

Add it to Eleventy config file (usually eleventy.config.js)

// ES module
import clean from "eleventy-plugin-clean";

export default function(eleventyConfig) {
  eleventyConfig.addPlugin(clean);
};

// CommonJS
module.exports = async function(eleventyConfig) {
  const clean = (await import("eleventy-plugin-clean")).default;
  await eleventyConfig.addPlugin(clean);
};

For Eleventy 1.x and 2.x

npm install eleventy-plugin-clean@^1

Add it to Eleventy config file (usually .eleventy.js)

const clean = require("eleventy-plugin-clean");

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(clean);
};

Shared Setup for Eleventy 1.x, 2.x and 3.x

If you are using git, add the following line to your .gitignore.

.plugin-clean

If you are not using git, add it to your .eleventyignore file instead of the .gitignore file.

Usage

eleventy-plugin-clean does not delete files which were not written by Eleventy or had been created before the installation of the plugin.

Therefore, you may want to clean the output directory once before using it.

rm -rf _site/*

What it actually does

eleventy-plugin-clean uses LMDB, a key-value store, to store all the data needed to keep the output directory clean. The DB is located at .plugin-clean in your project root.

It keeps the build number of Eleventy project. The build number is an integer value that it automatically increases with each Eleventy build.

It uses the key-value store to store build numbers for the files in the output directory. In other words, eleventy-plugin-clean knows all of the files in the output directory and each of the file records has its build number that generated the file.

When Eleventy (re)builds the site, it updates the build numbers for all of the output files generated by the build.

At the end of each build, it removes the files in the output directory which have a build number older than the current build number and deletes their records from the key-value store.

Plugins

If you are using plugins that write files in the output directory by itself instead of using Eleventy, eleventy-plugin-clean does not delete such files when they are no longer created/updated.

Such plugins need to call updateFileRecord(outputPath, inputPath) for files to be managed by eleventy-plugin-clean.

For example, eleventy-sass does call updateFileRecord(), and all of the files in the output directory will be managed by eleventy-plugin-clean.

(eleventy-sass do use Eleventy's file writing functionality for CSS files compiled from Sass/SCSS files, but writes only source map files by itself, and it calls updateFileRecord() only for the source map files.)

API

updateFileRecord(outputPath, inputPath) is the only API function. It is used for files to be managed by eleventy-plugin-clean.

inputPath is optional and used only for debug purpose. Therefore, you can call it only with outputPath.

const clean = require("eleventy-plugin-clean");

clean.updateFileRecord(outputPath);

Limitations

Suppose you are running npx @11ty/eleventy --serve.

eleventy-plugin-clean does not detect file deletions since Eleventy doesn't listen unlink events but only listens change and add events:

https://github.com/11ty/eleventy/blob/1db6a10a98f35b6f6bcac94222cdd8597e6f7928/src/Eleventy.js#L953-L961

Therefore, when you remove a file from your input directory, nothing will happen.

However, after that, if you change or add another file or if you re-run npx @11ty/eleventy --serve or npx @11ty/eleventy, it will remove the file(s) in the output directory which had been generated from the above removed file.