{"id":14772,"library":"nuxt-build-cache","title":"Nuxt Build Cache","description":"Nuxt Build Cache is an experimental module for Nuxt 3 designed to significantly accelerate CI/CD build processes by caching generated `.nuxt/` artifacts. Currently at version 0.1.1, its release cadence is irregular as it's under active development. The module works by collecting build outputs into a tar file after a `nuxt build`. On subsequent builds, it generates a content-based hash from various sources including Nuxt configuration, files in known Nuxt directories (like `pages/`, `layouts/`), and key project root files (`package.json`, lock-files). If this hash remains unchanged, it bypasses the Vite/Webpack build step and restores the cached build, potentially reducing build times by up to 2x. This mechanism is particularly beneficial when only prerendered content or server routes have changed, differentiating it from traditional file-based caching by focusing on a comprehensive content hash. It aims to replicate similar build performance improvements seen in Nuxt 2.","status":"active","version":"0.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/pi0/nuxt-build-cache","tags":["javascript","typescript"],"install":[{"cmd":"npm install nuxt-build-cache","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-build-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-build-cache","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This type represents the configuration options for the `nuxt-build-cache` module. While exported, it currently defines an empty object, indicating minimal user-configurable options at this experimental stage.","symbol":"ModuleOptions","correct":"import type { ModuleOptions } from 'nuxt-build-cache'"},{"note":"The primary way to 'import' and activate this module is by adding its string name to the `modules` array within your `nuxt.config.ts` file. It does not expose a default JavaScript symbol for direct import.","wrong":"import { 'nuxt-build-cache' } from 'nuxt-build-cache'","symbol":"'nuxt-build-cache'","correct":"export default defineNuxtConfig({\n  modules: [\n    'nuxt-build-cache'\n  ]\n})"},{"note":"While not part of `nuxt-build-cache` itself, `defineNuxtConfig` from the `nuxt` package is essential for setting up your Nuxt 3 configuration, including registering `nuxt-build-cache` as a module. It provides type-checking and autocompletion for your Nuxt configuration object.","symbol":"defineNuxtConfig","correct":"import { defineNuxtConfig } from 'nuxt';"}],"quickstart":{"code":"npx nuxi module add nuxt-build-cache\n\n// Then, in your nuxt.config.ts:\nimport { defineNuxtConfig } from 'nuxt';\n\nexport default defineNuxtConfig({\n  modules: [\n    'nuxt-build-cache'\n  ],\n  // Optional: Disable the cache entirely via environment variable\n  // NUXT_DISABLE_BUILD_CACHE=true\n  // Optional: Skip restoring cache even if it exists via environment variable\n  // NUXT_IGNORE_BUILD_CACHE=true\n});","lang":"typescript","description":"This quickstart demonstrates how to add the `nuxt-build-cache` module using the Nuxt CLI and then configure it in your `nuxt.config.ts`."},"warnings":[{"fix":"Thoroughly test in non-production environments before deploying to critical systems. Monitor the GitHub repository for updates and stability reports.","message":"This module is explicitly labeled as 'highly experimental' and should be used at your own risk. It may contain instabilities or breaking changes in future versions.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Avoid dynamic values in `nuxt.config.ts` that change with every build. For runtime-specific configurations, prefer using environment variables, which will be correctly included in the hash if updated.","message":"The caching mechanism relies on content-based hashing of your Nuxt configuration. If your `nuxt.config.ts` contains dynamic values (e.g., `date: new Date()`), the cache hash will change on every build, preventing effective caching.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"If unexpected build times or stale content occur, consider clearing the cache manually (e.g., `rm -rf node_modules/.cache/nuxt/build`) or temporarily disabling the module via `NUXT_DISABLE_BUILD_CACHE=true`.","message":"While designed to speed up builds, issues with the internal hashing mechanism (which uses `unjs/ohash`) could lead to cache misses or stale caches if changes are not correctly detected or if the cache is corrupted.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `NUXT_DISABLE_BUILD_CACHE` is not set to `true` and `NUXT_IGNORE_BUILD_CACHE` is not set. Review your `nuxt.config.ts` for any dynamic values that might change on each build.","cause":"The module might be disabled, ignored, or dynamic configuration values are preventing consistent hashes.","error":"Cache not being used or build time not reduced significantly."},{"fix":"Manually clear the build cache by removing `node_modules/.cache/nuxt/build/` and try rebuilding. Report the issue to the module's maintainers if it persists, providing details on what changes were not detected.","cause":"The cache hash might not have accurately captured all relevant changes, leading to an old build being restored.","error":"Changes not reflected in cached build."}],"ecosystem":"npm"}