Watch the 40-minute walkthrough video on how to contribute to Next.js.
- Read about our Commitment to Open Source.
- To contribute to our examples, please see Adding examples below.
- Before jumping into a PR be sure to search existing PRs or issues for an open or closed item that relates to your submission.
The development branch is canary
. This is the branch that all pull
requests should be made against. The changes on the canary
branch are published to the @canary
tag on npm regularly.
To develop locally:
-
Fork this repository to your own GitHub account and then clone it to your local device.
If you don't need the whole git history, you can clone with depth 1 to reduce the download size (~1.6GB):
git clone --depth=1 https://github.com/vercel/next.js
-
Create a new branch:
git checkout -b MY_BRANCH_NAME
-
Install pnpm:
npm install -g pnpm
-
Install the dependencies with:
pnpm install
-
Start developing and watch for code changes:
pnpm dev
-
In a new terminal, run
pnpm types
to compile declaration files from TypeScript.Note: You may need to repeat this step if your types get outdated.
For instructions on how to build a project with your local version of the CLI, see Developing with your local version of Next.js below. (Naively linking the binary is not sufficient to develop locally.)
You can build the project, including all type definitions, with:
pnpm build
# - or -
pnpm prepublishOnly
By default the latest canary of the next-swc binaries will be installed and used. If you are actively working on Rust code or you need to test out the most recent Rust code that hasn't been published as a canary yet you can install Rust and run pnpm --filter=@next/swc build-native
.
If you want to test out the wasm build locally, you will need to install wasm-pack. Run pnpm --filter=@next/swc build-wasm --target <wasm_target>
to build and node ./scripts/setup-wasm.mjs
to copy it into your node_modules
. Run next with NODE_OPTIONS='--no-addons'
to force it to use the wasm binary.
If you need to clean the project for any reason, use pnpm clean
.
See the testing readme for information on writing tests.
pnpm testonly
If you would like to run the tests in headless mode (with the browser windows hidden) you can do
pnpm testheadless
Running a specific test suite (e.g. production
) inside of the test/integration
directory:
pnpm testonly --testPathPattern "production"
Running one test in the production
test suite:
pnpm testonly --testPathPattern "production" -t "should allow etag header support"
To check the formatting of your code:
pnpm lint
If you get errors, you can fix them with:
pnpm lint-fix
Running examples can be done with:
pnpm next ./examples/basic-css/
To figure out which pages are available for the given example, you can run:
EXAMPLE=./test/integration/basic
(\
cd $EXAMPLE/pages; \
find . -type f \
| grep -v '\.next' \
| sed 's#^\.##' \
| sed 's#index\.js##' \
| sed 's#\.js$##' \
| xargs -I{} echo localhost:3000{} \
)
There are two options to develop with your local version of the codebase:
-
In your app's
package.json
, replace:"next": "<next-version>",
with:
"next": "file:/path/to/next.js/packages/next",
-
In your app's root directory, make sure to remove
next
fromnode_modules
with:rm -rf ./node_modules/next
-
In your app's root directory, run:
pnpm i
to re-install all of the dependencies.
Note that Next will be copied from the locally compiled version as opposed to from being downloaded from the NPM registry.
-
Run your application as you normally would.
-
To update your app's dependencies, after you've made changes to your local
next
repository. In your app's root directory, run:pnpm install --force
- If you see the below error while running
pnpm dev
with next:
Failed to load SWC binary, see more info here: https://nextjs.org/docs/messages/failed-loading-swc
Try to add the below section to your package.json
, then run again
"optionalDependencies": {
"@next/swc-linux-x64-gnu": "canary",
"@next/swc-win32-x64-msvc": "canary",
"@next/swc-darwin-x64": "canary",
"@next/swc-darwin-arm64": "canary"
},
-
Move your app inside of the Next.js monorepo.
-
Run with
pnpm next-with-deps ./app-path-in-monorepo
This will use the version of next
built inside of the Next.js monorepo and the
main pnpm dev
monorepo command can be running to make changes to the local
Next.js version at the same time (some changes might require re-running pnpm next-with-deps
to take effect).
Our documentation currently leverages a manifest file which is how documentation entries are checked.
When adding a new entry under an existing category you only need to add an entry with {title: '', path: '/docs/path/to/file.md'}
. The "title" is what is shown on the sidebar.
When moving the location/url of an entry the "title" field can be removed from the existing entry and the ".md" extension removed from the "path", then a "redirect" field with the shape of {permanent: true/false, destination: '/some-url'}
can be added. A new entry should be added with the "title" and "path" fields if the document was renamed within the docs
folder that points to the new location in the folder e.g. /docs/some-url.md
Example of moving documentation file:
Before:
[
{
"path": "/docs/original.md",
"title": "Hello world"
}
]
After:
[
{
"path": "/docs/original",
"redirect": {
"permanent": false,
"destination": "/new"
}
}
{
"path": "/docs/new.md",
"title": "Hello world"
},
]
Note: the manifest is checked automatically in the "lint" step in CI when opening a PR.
In Next.js we have a system to add helpful links to warnings and errors.
This allows for the logged message to be short while giving a broader description and instructions on how to solve the warning/error.
In general, all warnings and errors added should have these links attached.
Below are the steps to add a new link:
-
Run
pnpm new-error
which will create the error document and update the manifest automatically. -
Add the following url to your warning/error:
https://nextjs.org/docs/messages/<file-path-without-dotmd>
.For example, to link to
errors/api-routes-static-export.md
you use the url:https://nextjs.org/docs/messages/api-routes-static-export
When you add an example to the examples directory, please follow these guidelines to ensure high quality examples:
- TypeScript should be leveraged for new examples (no need for separate JavaScript and TypeScript examples, converting old JavaScript examples is preferred)
- Examples should not add custom ESLint configuration (we have specific templates for ESLint)
- If API routes aren't used in an example, they should be omitted
- If an example exists for a certain library and you would like to showcase a specific feature of that library, the existing example should be updated (instead of adding a new example)
- Package manager specific config should not be added (e.g.
resolutions
inpackage.json
) - In
package.json
the version ofnext
(andeslint-config-next
) should belatest
- In
package.json
the dependency versions should be up-to-date - Use
export default function
for page components and API Routes instead ofconst
/let
(The exception is if the page hasgetInitialProps
, in which caseNextPage
could be useful) - CMS example directories should be prefixed with
cms-
- Example directories should not be prefixed with
with-
- Make sure linting passes (you can run
pnpm lint-fix
)
Also don’t forget to add a README.md
file with the following format:
- Replace
DIRECTORY_NAME
with the directory name you’re adding. - Fill in
Example Name
andDescription
. - Examples should be TypeScript first, if possible.
- Omit the
name
andversion
fields from yourpackage.json
. - Ensure all your dependencies are up to date.
- Ensure you’re using
next/image
. - To add additional installation instructions, please add it where appropriate.
- To add additional notes, add
## Notes
section at the end. - Remove the
Deploy your own
section if your example can’t be immediately deployed to Vercel.
# Example Name
Description
## Deploy your own
Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/DIRECTORY_NAME&project-name=DIRECTORY_NAME&repository-name=DIRECTORY_NAME)
## How to use
Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
```bash
npx create-next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
```
```bash
yarn create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
```
```bash
pnpm create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
```
Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
Repository maintainers can use yarn publish-canary
to publish a new version of all packages to npm.
Repository maintainers triage every issue and PR opened in the repository.
Issues are opened with one of these labels:
template: story
- a feature request, converted to an 💡 Ideas discussiontemplate: bug
- unverified issue with Next.js itself, or one of the examples in theexamples
foldertemplate: documentation
- feedback for improvement or an unverified issue with the Next.js documentation
In case of a bug report, a maintainer looks at the provided reproduction. If the reproduction is missing or insufficient, a please add a complete reproduction
label is added. If a reproduction is not provided for more than 30 days, the issue becomes stale and will be automatically closed. If a reproduction is provided within 30 days, the please add a complete reproduction
label is removed and the issue will not become stale anymore.
Bug reports must be verified against the next@canary
release. The canary version of Next.js ships daily and includes all features and fixes that have not been released to the stable version yet. Think of canary as a public beta. Some issues may already be fixed in the canary version, so please verify that your issue reproduces before opening a new issue. Issues not verified against next@canary
will be closed after 30 days.
If the issue is specific to the project and not to Next.js itself, it might be converted to a 🎓️ Help discussion
If the bug is verified, it will receive the kind: bug
label and will be tracked by the maintainers. An area:
label can be added to indicate which part of Next.js is affected.
Confirmed issues never become stale or be closed before resolution.
All closed PRs and Issues will be locked after 30 days of inactivity (eg.: comment, referencing from elsewhere).