Registry / devops / netlify-plugin-ttl-cache

netlify-plugin-ttl-cache

library1.0.2jsnpmunverified

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.

devops

npm install netlify-plugin-ttl-cache

github ↗package ↗

INSTALL

IMPORT

SIG · NETLIFY-PLUGIN-TTL

netlify-plugin-ttl-cache

devopsjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

netlify-plugin-ttl-cache

✓ [[plugins]] package = "netlify-plugin-ttl-cache"

✗ import '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

✓ [plugins.inputs] path = "build"

✗ path: 'build'

The `path` input specifies the build output directory to cache. It must be a string in the `[plugins.inputs]` table.

ttl

✓ [plugins.inputs] ttl = 90

✗ ttl = "90"

The `ttl` input specifies the maximum age in days for cached files. It must be a number (integer) in `netlify.toml`.

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

Debug

Known issues

gotchaMisconfiguring 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).

affects: >=1.0.0

gotchaSetting 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.

affects: >=1.0.0

gotchaThis 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.

affects: >=1.0.0

Errors

Common errors & fixes

ChunkLoadError: Loading chunk {chunkId} failed.

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.

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.

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).

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/andyrichardson/netlify-plugin-ttl-cache ↗

packagehttps://www.npmjs.com/package/netlify-plugin-ttl-cache ↗