How to contribute

Next.js is an open-source project; outside contributions go through the same review process as Vercel-internal work.

Where to start

• Issues labeled good first issue on github.com/vercel/next.js/issues are scoped to be approachable.
• Reproduction repos — most bug reports include a minimal reproduction. The repro is the spec; reproduce it locally and write a test that fails before fixing.
• Existing PRs — search PRs and issues before opening a new one. The framework moves fast and there's a good chance someone has already filed it.

The full contributor guide lives at contributing.md and the deep-dive guides under contributing/. Read those before opening a non-trivial PR.

The pull request lifecycle

graph LR
    Fork[Fork repo] --> Branch[Create branch]
    Branch --> Code[Code change]
    Code --> Sign[Sign commits]
    Sign --> Push[Push branch]
    Push --> PR[Open PR]
    PR --> CI[CI runs<br/>build + lint + tests]
    CI --> Review[Review]
    Review --> Merge[Squash merge]

Signed commits are required

Protected branches require verified commit signatures. Configure GPG, SSH, or S/MIME signing on your local Git before contributing — see the GitHub docs on signing. A Signed-off-by: trailer is not enough.

If your PR includes unsigned commits you will need to re-sign them and force-push.

PR description boilerplate

Every PR description must include the HTML comment

<!-- NEXT_JS_LLM_PR -->

at the bottom. This is enforced by the PR-status tooling.

Write the description focused on what changed and why, not what the diff already shows. Skip "Generated with…" / co-author footers — they are not desired in this repo.

Don't mark PRs ready for review yourself

The convention here is to leave PRs in Draft status and let the maintainers move them out of draft when they are queued for review. Do not run gh pr ready.

Definition of done

A PR is ready when:

1. CI is green: build, lint, types, and the relevant test suite all pass.
2. New behavior has at least one test (unit if applicable; otherwise an e2e or integration test).
3. Existing snapshots that legitimately changed are regenerated and reviewed.
4. The change does not break the public API surface without a corresponding documentation update under docs/.
5. For new feature flags: type, schema, define-env, and runtime env are all wired (see patterns and conventions).

Sub-pages

• Development workflow — branch, code, test, PR cycle; iteration tips
• Testing — the test matrix, fixture conventions, common gotchas
• Debugging — log flags, source map gotchas, runtime debug
• Patterns and conventions — coding style, error handling, feature-flag plumbing, edge constraints
• Tooling — build system, linters, code generators, CI and pre-commit