turbopackFileSystemCache

Core Idea

Cache persistente do Turbopack em disco (.next/dev/cache/turbopack e .next/cache/turbopack) que reduz trabalho repetido entre execuções de next dev ou next build, acelerando builds e sessões de dev subsequentes.

Key Concepts

• turbopackFileSystemCacheForDev (default true): cacheia o trabalho do next dev; reiniciar o dev server reaproveita a compilação anterior.
• turbopackFileSystemCacheForBuild (default true): cacheia o trabalho do next build em .next/cache/turbopack; builds subsequentes começam "quentes".
• Build environments: builds só ficam mais rápidos se .next/cache for restaurado antes de cada build; builds containerizados começam de layer limpa e não carregam o cache a menos que você monte/persista explicitamente.

Code Examples

const nextConfig: NextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true,
    turbopackFileSystemCacheForBuild: true,
  },
}

• O que demonstra: ambas as flags de cache, dev e build, no valor default (ligadas).

Reference Tables

Version	Changes
v16.3.0	FileSystem caching habilitado por default para builds.
v16.1.0	FileSystem caching habilitado por default para development.
v16.0.0	Beta release com flags separadas para build e dev.
v15.5.0	Cache persistente lançado como experimental em canary releases.

Anti-patterns

• Deixar turbopackFileSystemCacheForBuild: true em ambiente CI que nunca persiste .next/cache: escreve um cache que nunca será lido; setar false nesse caso evita trabalho desperdiçado.

Key Takeaways

1. Self-hosted builds que reutilizam o mesmo working directory se beneficiam automaticamente; builds containerizados exigem cache/mount explícito.
2. Em CI, configure build caching para o diretório .next/cache (ver guia CI build caching) para o cache do Turbopack ter efeito.
3. Ambas as flags de cache já vêm true por default desde a v16.1.0 (dev) e v16.3.0 (build).

Connects To

• CI build caching (guides/ci-build-caching): como configurar persistência de .next/cache no provedor de CI.
• turbopackMemoryEviction: controla como a memória é liberada quando esse cache em disco está ativo.