Unverified Commit 521f88e1 authored by Hunter Tunnicliff's avatar Hunter Tunnicliff Committed by GitHub

Move CI build cache instructions to Deployment docs (#35418)

This PR moves the instructions for configuring CI providers to preserve Next.js's build cache out of the _No Cache Detected_ error message and into ~the _Deployment_~ a new page within the _Advanced Features_ docs. 

This change is beneficial because it makes the CI configuration examples visible in the context of other helpful documentation for deploying Next.js.

👉 **Prior to this change, these CI configuration examples didn't show up in the Next.js docs.**

The relocated instructions are now linked on the _No Cache Detected_ error message page.

## Documentation / Examples

- [x] Make sure the linting passes by running `yarn lint`
Co-authored-by: 's avatarLee Robinson <me@leerob.io>
Co-authored-by: 's avatarSteven <steven@ceriously.com>
parent 092346d3
---
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 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://nextjs.org/docs/messages/no-cache) 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'
```
......@@ -258,6 +258,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"
......
......@@ -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@v3
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](https://nextjs.org/docs/advanced-features/ci-build-caching) to ensure your Next.js cache is persisted between builds.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment