From e3504c8693e82fd776e0235689fecd6e325418df Mon Sep 17 00:00:00 2001 From: Hunter Tunnicliff Date: Thu, 17 Mar 2022 15:29:05 -0700 Subject: [PATCH 1/4] Move CI build cache instructions to deployment docs --- docs/deployment.md | 126 +++++++++++++++++++++++++++++++++++++++++++++ errors/no-cache.md | 120 +----------------------------------------- 2 files changed, 127 insertions(+), 119 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 0049dff3e6425..7221559733ff2 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -98,6 +98,132 @@ Next.js will automatically load the latest version of your application in the ba **Note:** If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Navigating to a page that has _not_ been prefetched (and is not cached at the CDN level) will load the latest version. +## CI Build Caching + +To improve build performance, Next.js saves a cache to `.next/cache` that is shared between builds. + +To take advantage of this cache in a continuous integration environment, your CI workflow will need to be configured to correctly persist the cache between builds. + +> If your CI is not configured to persist `.next/cache` between builds, you may see a [No Cache Detected](https://github.com/vercel/next.js/tree/canary/errors/no-cache.md) error. + +Here are some example cache configurations for common CI providers: + +### Vercel + +Next.js caching is automatically configured for you. There's no action required on your part. + +### CircleCI + +Edit your `save_cache` step in `.circleci/config.yml` to include `.next/cache`: + +```yaml +steps: + - save_cache: + key: dependency-cache-{{ checksum "yarn.lock" }} + paths: + - ./node_modules + - ./.next/cache +``` + +If you do not have a `save_cache` key, please follow CircleCI's [documentation on setting up build caching](https://circleci.com/docs/2.0/caching/). + +### Travis CI + +Add or merge the following into your `.travis.yml`: + +```yaml +cache: + directories: + - $HOME/.cache/yarn + - node_modules + - .next/cache +``` + +### GitLab CI + +Add or merge the following into your `.gitlab-ci.yml`: + +```yaml +cache: + key: ${CI_COMMIT_REF_SLUG} + paths: + - node_modules/ + - .next/cache/ +``` + +### Netlify CI + +Use [Netlify Plugins](https://www.netlify.com/products/build/plugins/) with [`@netlify/plugin-nextjs`](https://www.npmjs.com/package/@netlify/plugin-nextjs). + +### AWS CodeBuild + +Add (or merge in) the following to your `buildspec.yml`: + +```yaml +cache: + paths: + - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i` + - '.next/cache/**/*' # Cache Next.js for faster application rebuilds +``` + +### GitHub Actions + +Using GitHub's [actions/cache](https://github.com/actions/cache), add the following step in your workflow file: + +```yaml +uses: actions/cache@v2 +with: + # See here for caching with `yarn` https://github.com/actions/cache/blob/main/examples.md#node---yarn or you can leverage caching with actions/setup-node https://github.com/actions/setup-node + path: | + ~/.npm + ${{ github.workspace }}/.next/cache + # Generate a new cache whenever packages or source files change. + key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }} + # If source files changed but packages didn't, rebuild from a prior cache. + restore-keys: | + ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}- +``` + +### Bitbucket Pipelines + +Add or merge the following into your `bitbucket-pipelines.yml` at the top level (same level as `pipelines`): + +```yaml +definitions: + caches: + nextcache: .next/cache +``` + +Then reference it in the `caches` section of your pipeline's `step`: + +```yaml +- step: + name: your_step_name + caches: + - node + - nextcache +``` + +### Heroku + +Using Heroku's [custom cache](https://devcenter.heroku.com/articles/nodejs-support#custom-caching), add a `cacheDirectories` array in your top-level package.json: + +```javascript +"cacheDirectories": [".next/cache"] +``` + +### Azure Pipelines + +Using Azure Pipelines' [Cache task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/cache), add the following task to your pipeline yaml file somewhere prior to the task that executes `next build`: + +```yaml +- task: Cache@2 + displayName: 'Cache .next/cache' + inputs: + key: next | $(Agent.OS) | yarn.lock + path: '$(System.DefaultWorkingDirectory)/.next/cache' +``` + ## Related For more information on what to do next, we recommend the following sections: diff --git a/errors/no-cache.md b/errors/no-cache.md index b3b0214ca31ff..e639422fc4f17 100644 --- a/errors/no-cache.md +++ b/errors/no-cache.md @@ -11,122 +11,4 @@ This results in slower builds and can hurt Next.js' persistent caching of client > **Note**: If this is a new project, or being built for the first time in your CI, you can ignore this error. > However, you'll want to make sure it doesn't continue to happen and fix it if it does! -Configure Next.js' cache to be persisted across builds. Next.js stores its cache in the `.next/cache` directory. - -Storing this folder across builds varies by CI provider. We've provided a list of a few common providers below. - -#### Vercel - -Next.js caching is automatically configured for you. There's no action required on your part. - -#### CircleCI - -Edit your `save_cache` step in `.circleci/config.yml` to include `.next/cache`: - -```yaml -steps: - - save_cache: - key: dependency-cache-{{ checksum "yarn.lock" }} - paths: - - ./node_modules - - ./.next/cache -``` - -If you do not have a `save_cache` key, please follow CircleCI's [documentation on setting up build caching](https://circleci.com/docs/2.0/caching/). - -#### Travis CI - -Add or merge the following into your `.travis.yml`: - -```yaml -cache: - directories: - - $HOME/.cache/yarn - - node_modules - - .next/cache -``` - -#### GitLab CI - -Add or merge the following into your `.gitlab-ci.yml`: - -```yaml -cache: - key: ${CI_COMMIT_REF_SLUG} - paths: - - node_modules/ - - .next/cache/ -``` - -#### Netlify CI - -Use [Netlify Plugins](https://www.netlify.com/products/build/plugins/) with [`@netlify/plugin-nextjs`](https://www.npmjs.com/package/@netlify/plugin-nextjs). - -#### AWS CodeBuild - -Add (or merge in) the following to your `buildspec.yml`: - -```yaml -cache: - paths: - - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i` - - '.next/cache/**/*' # Cache Next.js for faster application rebuilds -``` - -#### GitHub Actions - -Using GitHub's [actions/cache](https://github.com/actions/cache), add the following step in your workflow file: - -```yaml -uses: actions/cache@v2 -with: - # See here for caching with `yarn` https://github.com/actions/cache/blob/main/examples.md#node---yarn or you can leverage caching with actions/setup-node https://github.com/actions/setup-node - path: | - ~/.npm - ${{ github.workspace }}/.next/cache - # Generate a new cache whenever packages or source files change. - key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }} - # If source files changed but packages didn't, rebuild from a prior cache. - restore-keys: | - ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}- -``` - -#### Bitbucket Pipelines - -Add or merge the following into your `bitbucket-pipelines.yml` at the top level (same level as `pipelines`): - -```yaml -definitions: - caches: - nextcache: .next/cache -``` - -Then reference it in the `caches` section of your pipeline's `step`: - -```yaml -- step: - name: your_step_name - caches: - - node - - nextcache -``` - -#### Heroku - -Using Heroku's [custom cache](https://devcenter.heroku.com/articles/nodejs-support#custom-caching), add a `cacheDirectories` array in your top-level package.json: - -```javascript -"cacheDirectories": [".next/cache"] -``` - -#### Azure Pipelines - -Using Azure Pipelines' [Cache task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/cache), add the following task to your pipeline yaml file somewhere prior to the task that executes `next build`: - -```yaml -- task: Cache@2 - displayName: 'Cache .next/cache' - inputs: - key: next | $(Agent.OS) | yarn.lock - path: '$(System.DefaultWorkingDirectory)/.next/cache' -``` +Follow the instructions in [CI Build Caching](/docs/deployment.md#ci-build-caching) to ensure your Next.js cache is persisted between builds. From 4d44bb39b166ce81d228bd4efa616907c0c043b1 Mon Sep 17 00:00:00 2001 From: Hunter Tunnicliff Date: Tue, 5 Apr 2022 14:44:39 -0700 Subject: [PATCH 2/4] Create a new docs page for CI build caching --- docs/advanced-features/ci-build-caching.md | 129 +++++++++++++++++++++ docs/deployment.md | 126 -------------------- docs/manifest.json | 4 + errors/no-cache.md | 2 +- 4 files changed, 134 insertions(+), 127 deletions(-) create mode 100644 docs/advanced-features/ci-build-caching.md diff --git a/docs/advanced-features/ci-build-caching.md b/docs/advanced-features/ci-build-caching.md new file mode 100644 index 0000000000000..a5330a38d75d3 --- /dev/null +++ b/docs/advanced-features/ci-build-caching.md @@ -0,0 +1,129 @@ +--- +description: Learn how to configure CI to cache Next.js builds +--- + +# Continuous Integration (CI) Build Caching + +To improve build performance, Next.js saves a cache to `.next/cache` that is shared between builds. + +To take advantage of this cache in a continuous integration environment, your CI workflow will need to be configured to correctly persist the cache between builds. + +> If your CI is not configured to persist `.next/cache` between builds, you may see a [No Cache Detected](https://github.com/vercel/next.js/tree/canary/errors/no-cache.md) error. + +Here are some example cache configurations for common CI providers: + +## Vercel + +Next.js caching is automatically configured for you. There's no action required on your part. + +## CircleCI + +Edit your `save_cache` step in `.circleci/config.yml` to include `.next/cache`: + +```yaml +steps: + - save_cache: + key: dependency-cache-{{ checksum "yarn.lock" }} + paths: + - ./node_modules + - ./.next/cache +``` + +If you do not have a `save_cache` key, please follow CircleCI's [documentation on setting up build caching](https://circleci.com/docs/2.0/caching/). + +## Travis CI + +Add or merge the following into your `.travis.yml`: + +```yaml +cache: + directories: + - $HOME/.cache/yarn + - node_modules + - .next/cache +``` + +## GitLab CI + +Add or merge the following into your `.gitlab-ci.yml`: + +```yaml +cache: + key: ${CI_COMMIT_REF_SLUG} + paths: + - node_modules/ + - .next/cache/ +``` + +## Netlify CI + +Use [Netlify Plugins](https://www.netlify.com/products/build/plugins/) with [`@netlify/plugin-nextjs`](https://www.npmjs.com/package/@netlify/plugin-nextjs). + +## AWS CodeBuild + +Add (or merge in) the following to your `buildspec.yml`: + +```yaml +cache: + paths: + - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i` + - '.next/cache/**/*' # Cache Next.js for faster application rebuilds +``` + +## GitHub Actions + +Using GitHub's [actions/cache](https://github.com/actions/cache), add the following step in your workflow file: + +```yaml +uses: actions/cache@v2 +with: + # See here for caching with `yarn` https://github.com/actions/cache/blob/main/examples.md#node---yarn or you can leverage caching with actions/setup-node https://github.com/actions/setup-node + path: | + ~/.npm + ${{ github.workspace }}/.next/cache + # Generate a new cache whenever packages or source files change. + key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }} + # If source files changed but packages didn't, rebuild from a prior cache. + restore-keys: | + ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}- +``` + +## Bitbucket Pipelines + +Add or merge the following into your `bitbucket-pipelines.yml` at the top level (same level as `pipelines`): + +```yaml +definitions: + caches: + nextcache: .next/cache +``` + +Then reference it in the `caches` section of your pipeline's `step`: + +```yaml +- step: + name: your_step_name + caches: + - node + - nextcache +``` + +## Heroku + +Using Heroku's [custom cache](https://devcenter.heroku.com/articles/nodejs-support#custom-caching), add a `cacheDirectories` array in your top-level package.json: + +```javascript +"cacheDirectories": [".next/cache"] +``` + +## Azure Pipelines + +Using Azure Pipelines' [Cache task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/cache), add the following task to your pipeline yaml file somewhere prior to the task that executes `next build`: + +```yaml +- task: Cache@2 + displayName: 'Cache .next/cache' + inputs: + key: next | $(Agent.OS) | yarn.lock + path: '$(System.DefaultWorkingDirectory)/.next/cache' +``` diff --git a/docs/deployment.md b/docs/deployment.md index 7221559733ff2..0049dff3e6425 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -98,132 +98,6 @@ Next.js will automatically load the latest version of your application in the ba **Note:** If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Navigating to a page that has _not_ been prefetched (and is not cached at the CDN level) will load the latest version. -## CI Build Caching - -To improve build performance, Next.js saves a cache to `.next/cache` that is shared between builds. - -To take advantage of this cache in a continuous integration environment, your CI workflow will need to be configured to correctly persist the cache between builds. - -> If your CI is not configured to persist `.next/cache` between builds, you may see a [No Cache Detected](https://github.com/vercel/next.js/tree/canary/errors/no-cache.md) error. - -Here are some example cache configurations for common CI providers: - -### Vercel - -Next.js caching is automatically configured for you. There's no action required on your part. - -### CircleCI - -Edit your `save_cache` step in `.circleci/config.yml` to include `.next/cache`: - -```yaml -steps: - - save_cache: - key: dependency-cache-{{ checksum "yarn.lock" }} - paths: - - ./node_modules - - ./.next/cache -``` - -If you do not have a `save_cache` key, please follow CircleCI's [documentation on setting up build caching](https://circleci.com/docs/2.0/caching/). - -### Travis CI - -Add or merge the following into your `.travis.yml`: - -```yaml -cache: - directories: - - $HOME/.cache/yarn - - node_modules - - .next/cache -``` - -### GitLab CI - -Add or merge the following into your `.gitlab-ci.yml`: - -```yaml -cache: - key: ${CI_COMMIT_REF_SLUG} - paths: - - node_modules/ - - .next/cache/ -``` - -### Netlify CI - -Use [Netlify Plugins](https://www.netlify.com/products/build/plugins/) with [`@netlify/plugin-nextjs`](https://www.npmjs.com/package/@netlify/plugin-nextjs). - -### AWS CodeBuild - -Add (or merge in) the following to your `buildspec.yml`: - -```yaml -cache: - paths: - - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i` - - '.next/cache/**/*' # Cache Next.js for faster application rebuilds -``` - -### GitHub Actions - -Using GitHub's [actions/cache](https://github.com/actions/cache), add the following step in your workflow file: - -```yaml -uses: actions/cache@v2 -with: - # See here for caching with `yarn` https://github.com/actions/cache/blob/main/examples.md#node---yarn or you can leverage caching with actions/setup-node https://github.com/actions/setup-node - path: | - ~/.npm - ${{ github.workspace }}/.next/cache - # Generate a new cache whenever packages or source files change. - key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }} - # If source files changed but packages didn't, rebuild from a prior cache. - restore-keys: | - ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}- -``` - -### Bitbucket Pipelines - -Add or merge the following into your `bitbucket-pipelines.yml` at the top level (same level as `pipelines`): - -```yaml -definitions: - caches: - nextcache: .next/cache -``` - -Then reference it in the `caches` section of your pipeline's `step`: - -```yaml -- step: - name: your_step_name - caches: - - node - - nextcache -``` - -### Heroku - -Using Heroku's [custom cache](https://devcenter.heroku.com/articles/nodejs-support#custom-caching), add a `cacheDirectories` array in your top-level package.json: - -```javascript -"cacheDirectories": [".next/cache"] -``` - -### Azure Pipelines - -Using Azure Pipelines' [Cache task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/cache), add the following task to your pipeline yaml file somewhere prior to the task that executes `next build`: - -```yaml -- task: Cache@2 - displayName: 'Cache .next/cache' - inputs: - key: next | $(Agent.OS) | yarn.lock - path: '$(System.DefaultWorkingDirectory)/.next/cache' -``` - ## Related For more information on what to do next, we recommend the following sections: diff --git a/docs/manifest.json b/docs/manifest.json index ce6622372baf3..79a2565d8a2a2 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -255,6 +255,10 @@ "title": "`src` Directory", "path": "/docs/advanced-features/src-directory.md" }, + { + "title": "CI Build Caching", + "path": "/docs/advanced-features/ci-build-caching.md" + }, { "title": "Multi Zones", "path": "/docs/advanced-features/multi-zones.md" diff --git a/errors/no-cache.md b/errors/no-cache.md index e639422fc4f17..4e4b9963d9227 100644 --- a/errors/no-cache.md +++ b/errors/no-cache.md @@ -11,4 +11,4 @@ This results in slower builds and can hurt Next.js' persistent caching of client > **Note**: If this is a new project, or being built for the first time in your CI, you can ignore this error. > However, you'll want to make sure it doesn't continue to happen and fix it if it does! -Follow the instructions in [CI Build Caching](/docs/deployment.md#ci-build-caching) to ensure your Next.js cache is persisted between builds. +Follow the instructions in [CI Build Caching](https://nextjs.org/docs/advanced-features/ci-build-caching) to ensure your Next.js cache is persisted between builds. From 9d35e286f761e5a5e69a7198609915a85e807202 Mon Sep 17 00:00:00 2001 From: Hunter Tunnicliff Date: Wed, 6 Apr 2022 09:50:58 -0700 Subject: [PATCH 3/4] Use unabbreviated verbiage in build cache doc Co-authored-by: Lee Robinson --- docs/advanced-features/ci-build-caching.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/ci-build-caching.md b/docs/advanced-features/ci-build-caching.md index a5330a38d75d3..64631a0eebfa3 100644 --- a/docs/advanced-features/ci-build-caching.md +++ b/docs/advanced-features/ci-build-caching.md @@ -6,7 +6,7 @@ description: Learn how to configure CI to cache Next.js builds To improve build performance, Next.js saves a cache to `.next/cache` that is shared between builds. -To take advantage of this cache in a continuous integration environment, your CI workflow will need to be configured to correctly persist the cache between builds. +To take advantage of this cache in Continuous Integration (CI) environments, your CI workflow will need to be configured to correctly persist the cache between builds. > If your CI is not configured to persist `.next/cache` between builds, you may see a [No Cache Detected](https://github.com/vercel/next.js/tree/canary/errors/no-cache.md) error. From c4dc7d776e11649eb1d4b64f6245eb928cbd8f6f Mon Sep 17 00:00:00 2001 From: Steven Date: Wed, 11 May 2022 19:11:02 -0400 Subject: [PATCH 4/4] Update link to error --- docs/advanced-features/ci-build-caching.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/ci-build-caching.md b/docs/advanced-features/ci-build-caching.md index 64631a0eebfa3..1f72234056796 100644 --- a/docs/advanced-features/ci-build-caching.md +++ b/docs/advanced-features/ci-build-caching.md @@ -8,7 +8,7 @@ To improve build performance, Next.js saves a cache to `.next/cache` that is sha To take advantage of this cache in Continuous Integration (CI) environments, your CI workflow will need to be configured to correctly persist the cache between builds. -> If your CI is not configured to persist `.next/cache` between builds, you may see a [No Cache Detected](https://github.com/vercel/next.js/tree/canary/errors/no-cache.md) error. +> If your CI is not configured to persist `.next/cache` between builds, you may see a [No Cache Detected](https://nextjs.org/docs/messages/no-cache) error. Here are some example cache configurations for common CI providers: