{"id":14724,"library":"netlify-plugin-ttl-cache","title":"Netlify TTL Cache Plugin","description":"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.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/andyrichardson/netlify-plugin-ttl-cache","tags":["javascript","netlify","netlify-plugin","cache","ttl"],"install":[{"cmd":"npm install netlify-plugin-ttl-cache","lang":"bash","label":"npm"},{"cmd":"yarn add netlify-plugin-ttl-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add netlify-plugin-ttl-cache","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a Netlify build plugin, configured via `netlify.toml`. It does not expose JavaScript/TypeScript symbols for direct import into application code.","wrong":"import 'netlify-plugin-ttl-cache';","symbol":"netlify-plugin-ttl-cache","correct":"[[plugins]]\npackage = \"netlify-plugin-ttl-cache\""},{"note":"The `path` input specifies the build output directory to cache. It must be a string in the `[plugins.inputs]` table.","wrong":"path: 'build'","symbol":"path","correct":"[plugins.inputs]\npath = \"build\""},{"note":"The `ttl` input specifies the maximum age in days for cached files. It must be a number (integer) in `netlify.toml`.","wrong":"ttl = \"90\"","symbol":"ttl","correct":"[plugins.inputs]\nttl = 90"}],"quickstart":{"code":"npm i -D netlify-plugin-ttl-cache\n\n# netlify.toml\n[[plugins]]\npackage = \"netlify-plugin-ttl-cache\"\n  [plugins.inputs]\n  path = \"build\" # Your build output directory, e.g., 'dist', 'out'\n  ttl = 90 # Assets will be cached for 90 days\n  # exclude = \"^/_nuxt/\" # Optional: Regular expression string pattern for files to exclude","lang":"toml","description":"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."},"warnings":[{"fix":"Ensure the `path` input in `netlify.toml` accurately reflects your site's build output directory (e.g., `path = \"dist\"` for a `dist` folder).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Netlify's default build asset purging removes older, still-referenced JavaScript or CSS bundles from the CDN during new deployments.","error":"ChunkLoadError: Loading chunk {chunkId} failed."},{"fix":"Ensure the `path` input is present and correctly defined as a string, for example, `path = \"build\"`.","cause":"The `path` input in `netlify.toml` is either missing or provided with an incorrect data type (e.g., a number or boolean).","error":"Invalid configuration for plugin 'netlify-plugin-ttl-cache': Input 'path' must be a string."},{"fix":"Ensure the `ttl` input is present and correctly defined as a number (integer), for example, `ttl = 90` (without quotes).","cause":"The `ttl` input in `netlify.toml` is either missing, provided as a string (e.g., `ttl = \"90\"`), or another incorrect data type.","error":"Invalid configuration for plugin 'netlify-plugin-ttl-cache': Input 'ttl' must be a number."}],"ecosystem":"npm"}