CI Build Caching

Core Idea

Next.js grava cache de build em .next/cache, compartilhado entre builds; sem persistir essa pasta no seu provedor de CI, cada build recompila do zero (e pode disparar o erro "No Cache Detected").

Key Concepts

• .next/cache: diretório que precisa ser persistido/restaurado entre execuções de CI para acelerar next build.
• Vercel: cache configurado automaticamente, nenhuma ação necessária.
• Chave de cache por provedor: cada CI usa sua própria sintaxe de cache (lockfile hash, hash de arquivos fonte) para invalidar corretamente quando dependências ou código mudam.

Code Examples

# GitHub Actions — actions/cache
uses: actions/cache@v4
with:
  path: |
    ~/.npm
    ${{ github.workspace }}/.next/cache
  key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
  restore-keys: |
    ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

• O que demonstra: cache key composta (lockfile + fonte) com restore-keys de fallback quando só o lockfile bate.

# CircleCI
steps:
  - save_cache:
      key: dependency-cache-{{ checksum "yarn.lock" }}
      paths:
        - ./node_modules
        - ./.next/cache

• O que demonstra: padrão simples de incluir .next/cache junto de node_modules.

Reference Tables

Provedor	Onde configurar
Vercel	Automático, sem ação
CircleCI	save_cache em .circleci/config.yml, incluir .next/cache
Travis CI	cache.directories em .travis.yml
GitLab CI	cache.paths em .gitlab-ci.yml
Netlify	Plugin @netlify/plugin-nextjs
AWS CodeBuild	cache.paths em buildspec.yml
GitHub Actions	actions/cache@v4, path + key + restore-keys
Bitbucket Pipelines	definitions.caches + referenciar em step.caches
Heroku	cacheDirectories no package.json
Azure Pipelines	Task Cache@2 antes do next build
Jenkins	Plugin Job Cacher, arbitraryFileCache por path

Anti-patterns

• Não persistir .next/cache no CI: builds sempre partem do zero, mais lentos e sujeitos ao erro "No Cache Detected".
• Cache key sem hash de lockfile: cache fica desatualizado silenciosamente após mudança de dependência.

Key Takeaways

1. Cache de build (.next/cache) é diferente de cache de dados (fetch/use cache); este capítulo é só sobre acelerar next build em CI.
2. Vercel não exige configuração; qualquer outro provedor exige persistir .next/cache manualmente na config de cache do provedor.
3. A cache key ideal combina hash do lockfile (dependências) e hash dos arquivos fonte, com fallback via restore-keys.

Connects To

• Building: fases do next build que geram o conteúdo cacheado em .next/cache.
• Self-Hosting: contexto de deploy onde este cache de CI importa mais (builds próprios, não gerenciados pela Vercel).