Netlify 11ty Build Plugin

A plugin to make building with Eleventy and Netlify a joy!

Speed up your builds ⚡

• Caches images generated by @11ty/eleventy-img across builds
• Caches assets fetched by @11ty/eleventy-fetch across builds
• Caches any other folders of your choice (optional)

Install

Install plugin via your package manager of choice:

npm i netlify-plugin-11ty

And add the plugin to your netlify.toml file:

[[plugins]]
    package = "netlify-plugin-11ty"
    [plugins.inputs]
        # eleventy-img outputDir, path relative to publish directory
        cache_img = 'img/'
        cache_img_httpHeader = false

        # eleventy-fetch cacheDir, path relative to publish directory
        cache_assets = '../.cache/'
        cache_other = []

Make sure the path for cache_img is correct. Aand you're done! 🥳

You can read Netlify's documentation about Plugins here: https://docs.netlify.com/configure-builds/build-plugins/

Documentation

1. cache_img

Type: String or Array of Strings
Default: 'img' (relative to the publish directory)

Path to the folder(s) in which files generated by @11ty/eleventy-img are stored, relative to the publish directory. Can be a String or an array of Strings.

If set to false, files generated by @11ty/eleventy-img are not saved in Netlify cache.

2. cache_img_httpHeader

Type: Boolean
Default: false

If set to true, files generated by @11ty/eleventy-img will be served with http header cache-control: public, max-age=31536000, immutable.

Files generated by eleventy_img have a hash calculated using file content and Sharp plugin options in their name by default (starting from #116), so you can cache them indefinitely. Don't use this if you're using remote images.

:warning: Caution:

• If you are using remote images, this option should be false (default).
• If you are using custom filenames that don't include a hash, this option should be false (default).

3. cache_assets

Type: String or Array of Strings
Default: '../.cache' (relative to the publish directory)

Path to the folder(s) in which remote assets fetched by @11ty/eleventy-fetch are cached, relative to publish directory. Can be a String or an array of Strings.

If set to false, assets fetched by @11ty/eleventy-fetch are not saved in Netlify cache.

4. cache_other

Type: String or Array of Strings
Default: [] (relative to the publish directory)

Paths to any other folder(s) you'd like to cache across Netlify builds. If these folders exist before restoring Nelify cache, their content will be merged and overwritten with content from the cached folders.

FAQs

I rimraf my _site on every build

If your images are written to _site/img (default), use rimraf '_site/!(img)'.

If they are in a subdirectory, say _site/assets/images, use rimraf '_site/!(assets)' '_site/assets/!(images)'.

My builds are failing

If your build fails with

11:37:10 AM: Uncaught exception, the process will now terminate…
11:37:10 AM: Error: Unable to deserialize cloned data due to invalid or unsupported version.
11:37:10 AM:     at parseChannelMessages (node:internal/child_process/serialization:97:20)
11:37:10 AM:     at parseChannelMessages.next (<anonymous>)
11:37:10 AM:     at Pipe.channel.onread (node:internal/child_process:619:18)

or with

12:27:30 PM: ────────────────────────────────────────────────────────────────
12:27:30 PM:   Configuration error                                           
12:27:30 PM: ────────────────────────────────────────────────────────────────
12:27:30 PM: ​
12:27:30 PM:   Error message
12:27:30 PM:   The Node.js version is 19.1.0 but the plugin "netlify-plugin-11ty" requires >=12.18.0 <18.0.0

The version of Node you're using is not supported by Netlify.

Try setting Node version to 16.x with

echo "16" > .nvmrc

More info about this error:

• https://answers.netlify.com/t/netlify-build-cache-error/78115/4
• https://answers.netlify.com/t/build-failing-after-upgrade-to-node-18/75774
• https://github.com/zeroby0/netlify-plugin-11ty/issues/3

See this guide for more ways to set Node versions: https://docs.netlify.com/configure-builds/manage-dependencies/

Why are my images are not being cached?

If you have lot of images (several hundreds or more), your build might be timing out before the cache is saved.

If you see Failed during stage 'building site': Command did not finish within the time limit in your build logs, try requesting an upgraded build time limit.

See this thread for more details: https://answers.netlify.com/t/images-not-cached/78448/2

If your builds are failing for some other reason, please create a new Issue.

Are there any Benchmarks?

Yes!

The speed-up, ofcourse, depends on how many images your website has, but here is a benchmark I used when developing this plugin:

| Run | No cache persistence | With cache persistence | | ---------------------- | -------------------- | ----------------------- | | 1st run (empty cache) | 11.74 seconds | 11.52 seconds | | 2nd run (filled cache) | 11.32 seconds | 131.82 milliseconds |

Read more

Recommended Netlify plugins

• Subfont
• Inline Critical CSS

Bug Reports, Feature Requests, and Ideas

Please create an issue :)

License

MIT

If you need this repository with a different License, please create an issue.