Configuring CI Build Caching for Next.js – Speeding Up Builds with .next/cache

Introduction

Next.js stores build cache in .next/cache to speed up builds and reduce server load. In CI environments, this cache must be persisted between builds to avoid the No Cache Detected warning and benefit from faster rebuilds.

Cache Configuration by CI Provider

Vercel

Next.js caching is automatically configured. No action is required.

CircleCI

Update your .circleci/config.yml to include:

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

Travis CI

Add the following to .travis.yml:

cache:
  directories:
    - $HOME/.cache/yarn
    - node_modules
    - .next/cache

GitLab CI

In .gitlab-ci.yml, add:

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .next/cache/

Netlify CI

Use the @netlify/plugin-nextjs plugin to enable caching automatically.

AWS CodeBuild

In buildspec.yml, add:

cache:
  paths:
    - 'node_modules/**/*'
    - '.next/cache/**/*'

GitHub Actions

Use actions/cache in your workflow:

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

Bitbucket Pipelines

In bitbucket-pipelines.yml:

definitions:
  caches:
    nextcache: .next/cache

Then reference it:

- step:
    name: your_step_name
    caches:
      - node
      - nextcache

Heroku

In package.json, add:

"cacheDirectories": [".next/cache"]

Azure Pipelines

Use the Cache@2 task:

- task: Cache@2
  displayName: 'Cache .next/cache'
  inputs:
    key: next | $(Agent.OS) | yarn.lock
    path: '$(System.DefaultWorkingDirectory)/.next/cache'

Jenkins (Pipeline)

Using Job Cacher plugin:

stage("Restore npm packages") {
  steps {
    writeFile file: "next-lock.cache", text: "$GIT_COMMIT"
    cache(caches: [
      arbitraryFileCache(
        path: "node_modules",
        includes: "**/*",
        cacheValidityDecidingFile: "package-lock.json"
      )
    ]) {
      sh "npm install"
    }
  }
}
stage("Build") {
  steps {
    writeFile file: "next-lock.cache", text: "$GIT_COMMIT"
    cache(caches: [
      arbitraryFileCache(
        path: ".next/cache",
        includes: "**/*",
        cacheValidityDecidingFile: "next-lock.cache"
      )
    ]) {
      sh "npm run build"
    }
  }
}

Conclusion

By properly configuring CI caching for Next.js, you can significantly reduce build time and improve performance. Persisting .next/cache across builds is key to unlocking these benefits.