CI Build Caching

Core Idea

Next.js salva cache de build em .next/cache, compartilhado entre builds; em CI isso só funciona se o workflow persistir esse diretório entre execuções, senão aparece o erro "No Cache Detected".

Key Concepts

• .next/cache: diretório que precisa ser persistido/restaurado pelo CI de build pra build.
• Vercel: cache já configurado automaticamente, nenhuma ação necessária.
• Outros provedores: CircleCI, Travis CI, GitLab CI, Netlify (via @netlify/plugin-nextjs), AWS CodeBuild, GitHub Actions, Bitbucket Pipelines, Heroku, Azure Pipelines, Jenkins, todos exigem configurar cache manualmente apontando pra .next/cache (e geralmente node_modules).

Code Examples

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: chave de cache do GitHub Actions combinando lockfile + hash de código fonte, com restore-keys como fallback quando só o código mudou.

Reference Tables

CI Provider	Onde configurar
Vercel	Automático, nenhuma ação
CircleCI	save_cache em .circleci/config.yml
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 no workflow
Bitbucket Pipelines	definitions.caches + caches no step
Heroku	cacheDirectories no package.json
Azure Pipelines	Task Cache@2
Jenkins	Plugin Job Cacher

Anti-patterns

• Não persistir .next/cache no CI: cada build recompila do zero, gerando erro "No Cache Detected" e builds mais lentos.

Key Takeaways

1. O ganho de performance de build no CI depende inteiramente de persistir .next/cache.
2. Cada provedor de CI tem sintaxe própria, mas o alvo é sempre o mesmo diretório.
3. Combinar cache de node_modules com .next/cache cobre tanto install quanto build.

Connects To

• ch292 Deploying: builds em CI alimentam o pipeline de deploy descrito lá.