KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

netlify-plugin-11ty

★ 30 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://github.com/11ty/eleventy-img) across builds
- Caches assets fetched by
  [@11ty/eleventy-fetch](https://github.com/11ty/eleventy-fetch) across builds
- Caches any other folders of your choice (optional)

## Install

Install plugin via your package manager of choice:

```bash
npm i netlify-plugin-11ty
```

And add the plugin to your `netlify.toml` file:

```toml
[[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`](#1-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](https://www.11ty.dev/docs/plugins/image/#advanced-control-of-sharp-image-processor)
in their name by default
([starting from #116](https://github.com/11ty/eleventy-img/pull/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](https://www.11ty.dev/docs/plugins/image/#custom-filenames-new-in-image-0.4.0)
  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](https://github.com/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

```log
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

```log
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

```bash
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](https://github.com/zeroby0/netlify-plugin-11ty/issues).

### 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](https://github.com/11ty/eleventy-img/pull/116#issuecomment-882870369)

## Recommended Netlify plugins

- [Subfont](https://github.com/munter/netlify-plugin-subfont)
- [Inline Critical CSS](https://github.com/Tom-Bonnike/netlify-plugin-inline-critical-css#readme)

## Bug Reports, Feature Requests, and Ideas

Please
[create an issue](https://github.com/zeroby0/netlify-plugin-11ty/issues/new/) :)

## License

**MIT**

If you need this repository with a different License, please
[create an issue](https://github.com/zeroby0/netlify-plugin-11ty/issues/new/).

netlify-plugin-11ty

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README