Netlify TTL Cache Plugin

1.0.2 · active · verified Sun Apr 19

netlify-plugin-ttl-cache is a Netlify build plugin designed to address common runtime errors, such as 'ChunkLoadError,' in single-page applications (SPAs) that utilize code splitting (e.g., `React.lazy`). Netlify's default behavior is to replace all static assets upon each new deployment, which can lead to issues if a user's browser attempts to load an old, cached JavaScript chunk that no longer exists on the server. This plugin, currently at version 1.0.2, mitigates this by allowing users to specify a build output directory and a Time-To-Live (TTL) for assets within it, effectively persisting legacy immutable assets across deployments for a defined period. This ensures that previously served assets remain available, preventing broken user experiences without manual intervention. The plugin is configured declaratively via `netlify.toml` and does not require changes to application JavaScript code.

Common errors

```
ChunkLoadError: Loading chunk {chunkId} failed.
```
cause Netlify's default build asset purging removes older, still-referenced JavaScript or CSS bundles from the CDN during new deployments.

fix Install `netlify-plugin-ttl-cache` and configure it in your `netlify.toml` with the correct `path` to your build output and an appropriate `ttl` value (e.g., `path = "build"`, `ttl = 90`).
```
Invalid configuration for plugin 'netlify-plugin-ttl-cache': Input 'path' must be a string.
```
cause The `path` input in `netlify.toml` is either missing or provided with an incorrect data type (e.g., a number or boolean).

fix Ensure the `path` input is present and correctly defined as a string, for example, `path = "build"`.
```
Invalid configuration for plugin 'netlify-plugin-ttl-cache': Input 'ttl' must be a number.
```
cause The `ttl` input in `netlify.toml` is either missing, provided as a string (e.g., `ttl = "90"`), or another incorrect data type.

fix Ensure the `ttl` input is present and correctly defined as a number (integer), for example, `ttl = 90` (without quotes).

Warnings

gotcha Misconfiguring the `path` input to point to an incorrect build output directory will result in the plugin failing to cache the intended assets, potentially leading to continued chunk-load errors despite plugin activation.
Fix: Ensure the `path` input in `netlify.toml` accurately reflects your site's build output directory (e.g., `path = "dist"` for a `dist` folder).
gotcha Setting the `ttl` (time-to-live) value too low (e.g., a few days for a site with infrequent visitors) can lead to assets expiring from the cache before all active users have updated their browser cache, reintroducing chunk-load errors. Conversely, an excessively high `ttl` can consume more Netlify build cache space than necessary.
Fix: Choose a `ttl` value (in days) that balances cache efficiency with user experience, typically ranging from 30 to 180 days for most applications with immutable assets. Monitor your site for any lingering chunk-load errors post-deployment.
gotcha This plugin is specifically designed for *immutable* build assets (e.g., hashed JavaScript/CSS chunks). If your build process generates assets with non-unique filenames across deployments, persisting them with this plugin could lead to serving outdated versions instead of the intended new ones, causing unexpected UI behavior.
Fix: Verify that your build tool (e.g., Webpack, Vite, Create React App) is configured to generate unique, content-hashed filenames for assets that are meant to be cached by this plugin.

Install

npm install netlify-plugin-ttl-cache npm
yarn add netlify-plugin-ttl-cache yarn
pnpm add netlify-plugin-ttl-cache pnpm

Imports

netlify-plugin-ttl-cache
wrong:
```
import 'netlify-plugin-ttl-cache';
```
correct:
```
[[plugins]]
package = "netlify-plugin-ttl-cache"
```
This package is a Netlify build plugin, configured via `netlify.toml`. It does not expose JavaScript/TypeScript symbols for direct import into application code.
path
wrong:
```
path: 'build'
```
correct:
```
[plugins.inputs]
path = "build"
```
The `path` input specifies the build output directory to cache. It must be a string in the `[plugins.inputs]` table.
ttl
wrong:
```
ttl = "90"
```
correct:
```
[plugins.inputs]
ttl = 90
```
The `ttl` input specifies the maximum age in days for cached files. It must be a number (integer) in `netlify.toml`.

Quickstart

This quickstart installs the plugin and configures it in `netlify.toml` to cache assets in the 'build' directory for 90 days, preventing chunk-load errors.

npm i -D netlify-plugin-ttl-cache

# netlify.toml
[[plugins]]
package = "netlify-plugin-ttl-cache"
  [plugins.inputs]
  path = "build" # Your build output directory, e.g., 'dist', 'out'
  ttl = 90 # Assets will be cached for 90 days
  # exclude = "^/_nuxt/" # Optional: Regular expression string pattern for files to exclude

view raw JSON →