Registry / devops / nuxt-build-cache

nuxt-build-cache

library0.1.1jsnpmunverified

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.

devops web-framework

npm install nuxt-build-cache

github ↗package ↗

INSTALL

IMPORT

SIG · NUXT-BUILD-CACHE

nuxt-build-cache

devopsjavascriptv0.1.1

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.

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'

✓ export default defineNuxtConfig({ modules: [ 'nuxt-build-cache' ] })

✗ import { 'nuxt-build-cache' } from '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.

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 });

Debug

Known issues

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

affects: >=0.1.0

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

affects: >=0.1.0

gotchaWhile 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`.

affects: >=0.1.0

Errors

Common errors & fixes

Cache not being used or build time not reduced significantly.

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.

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.

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/pi0/nuxt-build-cache ↗

packagehttps://www.npmjs.com/package/nuxt-build-cache ↗