Configuring Turbopack Cache for Next.js Projects

Turbopack’s caching layer operates as a deterministic state machine, persisting incremental compilation artifacts to disk or memory. In Next.js, cache configuration directly dictates build latency, memory footprint, and hot-reload fidelity. This guide covers disk versus memory allocation, Next.js integration points, cache lifecycle management, and performance tuning for incremental builds.

Understanding Turbopack’s Cache Architecture in Next.js

Turbopack stores compiled module graphs, transformed assets, and dependency metadata in .next/cache/turbopack. The directory maintains a strict mapping between source file hashes and cached transformation outputs. During incremental builds, the engine computes a content-addressable hash for each module. If the hash matches an existing cache entry, Turbopack bypasses transformation and injects the serialized AST directly.

Cache invalidation is tightly coupled to the module graph resolution pipeline. When a dependency changes, Turbopack propagates invalidation signals through the dependency tree, marking downstream nodes as stale while preserving unaffected subgraphs. For a deeper breakdown of how Turbopack tracks module dependencies and invalidates stale graphs, refer to our guide on Turbopack Incremental Compilation.

Core Configuration via next.config.mjs

Cache behavior is controlled through the experimental.turbopack namespace in next.config.mjs and supplemented by environment variables. The following configuration enforces disk-based caching with explicit directory routing and retention policies.

// next.config.mjs
export default {
 experimental: {
 turbopack: {
 cache: {
 dir: process.env.TURBOPACK_CACHE_DIR || '.next/cache/turbopack',
 strategy: 'disk',
 maxAge: 86400000 // 24 hours in milliseconds
 }
 }
 }
};

Environment variables override runtime defaults:

  • TURBOPACK_CACHE_DIR: Absolute or relative path to the cache root.
  • TURBOPACK_MEMORY_LIMIT: Maximum heap allocation for in-memory caching (defaults to 512MB).
  • TURBOPACK_CACHE_STRATEGY: 'disk', 'memory', or 'hybrid'.

Diagnostic Trigger: Warning: Turbopack cache directory is not writable Root Cause: Default cache paths frequently conflict with containerized environments, Docker volume mounts, or read-only filesystems. Unhandled fallbacks force volatile memory caching, eliminating persistence across restarts.

Resolution Steps:

  1. Define TURBOPACK_CACHE_DIR in .env.local pointing to a persistent volume.
  2. Set experimental.turbopack.cache.strategy to 'disk' in next.config.mjs.
  3. Verify directory permissions with chmod -R 755 <cache_dir>.
  4. Run next dev --turbopack and inspect .next/cache/turbopack for .turbopack state files.

Resolving TURBOPACK_CACHE_INVALID and Stale Build Artifacts

Cache corruption typically manifests after dependency upgrades, Node.js patch updates, or symlink topology changes. The engine detects hash divergence between the current module graph and persisted state, triggering explicit invalidation errors.

Diagnostic Triggers:

  • Error: TURBOPACK_CACHE_INVALID: Hash mismatch detected
  • Error: Failed to read cache entry: ENOENT

Root Cause: Module graph hashes diverge from stored state when package-lock.json mutates, Node.js binary interfaces shift, or symlink resolution alters file paths. Turbopack rejects partial reads to prevent corrupted AST injection.

Resolution Steps:

  1. Stop the dev server to release file locks.
  2. Execute rm -rf .next/cache/turbopack/* to clear stale state.
  3. Run next dev --turbopack to trigger a full cold rebuild.
  4. Verify successful cache regeneration via console output: [Turbopack] Cache initialized successfully.
  5. Implement a pre-commit hook to invalidate cache on package.json changes.
# .husky/pre-commit
#!/bin/sh
if git diff --cached --name-only | grep -qE 'package\.json|package-lock\.json'; then
 echo "Dependency manifest changed. Invalidating Turbopack cache..."
 rm -rf .next/cache/turbopack/*
fi

Optimizing Cache Performance for CI/CD Pipelines

CI environments lack persistent local storage. Without explicit cache restoration, every pipeline execution performs a cold build, negating Turbopack’s incremental advantages and increasing build duration. Remote caching and deterministic key generation are required to maintain pipeline velocity.

Diagnostic Trigger: Error: Cache restore failed: checksum mismatch Root Cause: Inconsistent cache keys or corrupted archive uploads cause checksum validation failures during restoration. The pipeline falls back to cold compilation.

Resolution Steps:

  1. Configure GitHub Actions cache action targeting .next/cache/turbopack.
  2. Use package-lock.json hash for cache key generation to ensure dependency parity.
  3. Add fallback restore-keys for partial cache hits during lockfile updates.
  4. Validate cache hit rate via CI logs and adjust TTL if stale artifacts persist.
# .github/workflows/build.yml
- name: Cache Turbopack
 uses: actions/cache@v3
 with:
 path: .next/cache/turbopack
 key: ${{ runner.os }}-turbopack-${{ hashFiles('**/package-lock.json') }}
 restore-keys: |
 ${{ runner.os }}-turbopack-

When aligning cache retention policies across multiple bundlers, consult the broader esbuild & Turbopack Workflows documentation for cross-toolchain compatibility patterns.

Troubleshooting Common Cache Misconfigurations

Cross-platform development introduces path normalization discrepancies, permission boundaries, and symlink resolution failures. Turbopack’s strict hashing algorithm rejects mismatched metadata, resulting in silent cache misses or explicit permission denials.

Diagnostic Triggers:

  • Error: EACCES: permission denied on cache dir
  • Error: Cache hash mismatch across environments

Root Cause: macOS/Linux/Windows filesystem differences alter path casing, line endings, or symlink targets. Turbopack computes different hashes for identical logical files, breaking cache portability.

Resolution Steps:

  1. Standardize cache paths using absolute paths or path.resolve() in configuration.
  2. Run ls -la .next/cache/turbopack to verify ownership matches the executing user.
  3. Disable symlink following in cache config if ENOTDIR errors occur during traversal.
  4. Use TURBOPACK_LOG=debug to trace cache read/write operations and isolate hash collisions.
# Enable verbose cache diagnostics
TURBOPACK_LOG=debug next dev --turbopack
← Back to Turbopack Incremental Compilation