Nuxt Build Cache

0.1.1 · active · verified Sun Apr 19

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.

Common errors

```
Cache not being used or build time not reduced significantly.
```
cause The module might be disabled, ignored, or dynamic configuration values are preventing consistent hashes.

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.
```
Changes not reflected in cached build.
```
cause The cache hash might not have accurately captured all relevant changes, leading to an old build being restored.

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.

Warnings

gotcha 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.
Fix: Thoroughly test in non-production environments before deploying to critical systems. Monitor the GitHub repository for updates and stability reports.
gotcha 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.
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.
gotcha 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.
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`.

Install

npm install nuxt-build-cache npm
yarn add nuxt-build-cache yarn
pnpm add nuxt-build-cache pnpm

Imports

ModuleOptions
```
import type { ModuleOptions } from 'nuxt-build-cache'
```
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.
'nuxt-build-cache'
wrong:
```
import { 'nuxt-build-cache' } from 'nuxt-build-cache'
```
correct:
```
export default defineNuxtConfig({
  modules: [
    'nuxt-build-cache'
  ]
})
```
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.
defineNuxtConfig
```
import { defineNuxtConfig } from 'nuxt';
```
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.

Quickstart

This quickstart demonstrates how to add the `nuxt-build-cache` module using the Nuxt CLI and then configure it in your `nuxt.config.ts`.

npx nuxi module add nuxt-build-cache

// Then, in your nuxt.config.ts:
import { defineNuxtConfig } from 'nuxt';

export default defineNuxtConfig({
  modules: [
    'nuxt-build-cache'
  ],
  // Optional: Disable the cache entirely via environment variable
  // NUXT_DISABLE_BUILD_CACHE=true
  // Optional: Skip restoring cache even if it exists via environment variable
  // NUXT_IGNORE_BUILD_CACHE=true
});

view raw JSON →