first commit

contributing/core/adding-error-links.md

@@ -0,0 +1,12 @@
+# Adding Warning and Error Descriptions
+
+Next.js has a system to add helpful links to warnings and errors.
+
+This allows the logged message to be short while giving a broader description and instructions on how to solve the warning/error on the documentation.
+
+In general, all warnings and errors added should have these links attached.
+
+Below are the steps to add a new link:
+
+1. Run `pnpm new-error` which will create the error document and update the manifest automatically.
+2. At the end of the command the URL for the error will be provided, add that to your error.

contributing/core/adding-features.md

@@ -0,0 +1,17 @@
+# Adding a new feature
+
+Anyone can propose a change to Next.js. However, adding new features often requires community discussions before proceeding with the implementation.
+
+Therefore, before opening a PR, you should use the [Feature Request discussion template](https://github.com/vercel/next.js/discussions/new?category=ideas) and collect feedback.
+
+## Why use a discussion?
+
+The discussion's goal is to achieve the following:
+
+1. **Verify the validity of the feature request**: The community can upvote discussions. Highly upvoted feature requests are more likely to be considered.
+2. **Understanding the consequences**: Any feature added to Next.js is likely to be around for a while and _has to be maintained_. This means that a new feature has to cover many use cases, needs to consider how it affects the ecosystem, and so on.
+3. **Looking at and understanding historical reasons for the current behavior or lack of the feature**: There might be a reason why a feature does not exist, or why the current implementation is in a certain way. There must be solid reasoning to change this, as the feature needs to be maintained even after it is added. (See 2.). Next.js has a strong policy on not breaking features, so any new feature has to be added in a way that makes it possible to incrementally adopt it.
+
+## Examples
+
+The Next.js team uses RFCs (Request For Comment), which you can find in [this discussion category](https://github.com/vercel/next.js/discussions/categories/rfc). Reading through these, you can get a better understanding of what is expected to be included in a good feature request.

contributing/core/building.md

@@ -0,0 +1,38 @@
+# Building
+
+You can build Next.js, including all type definitions and packages, with:
+
+```bash
+pnpm build
+```
+
+> [!TIP]
+> Next.js uses [taskr](https://www.npmjs.com/package/taskr) to parallelize the build tasks.
+> The tasks can be found in the [`taskfile.js`](../../packages/next/taskfile.js) file, and each task name refers to the name of the function to execute.
+> For example, `taskr release` will execute the `release()` function in the `taskfile.js` file.
+
+The build process consists of the three main tasks:
+
+- [Compile the TypeScript sources with SWC](#compile-the-typescript-sources-with-swc)
+- [Bundle the project with Webpack](#bundle-the-project-with-webpack)
+- [Generate the type definitions](#generate-the-type-definitions)
+
+### Compile the TypeScript Sources with SWC
+
+By default, the latest canary of the `next-swc` binaries will be installed and used to compile the TypeScript sources of the project. These sources are meant to be built inside the `packages/next/dist/...` directory. The outputs will include compiled JavaScript files and source maps.
+
+### Bundle the Project with Webpack
+
+Based on the outputs of the compilation, the project is then bundled with Webpack. The configuration can be found in the [`next-runtime.webpack-config.js`](../../packages/next/next-runtime.webpack-config.js) file.
+
+### Generate the Type Definitions
+
+The type definitions are generated using the TypeScript [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) compiler. You can build them separately with `pnpm types`. The [`tsconfig.build.json`](../../packages/next/tsconfig.build.json) is used which extends the base [`tsconfig.json`](../../packages/next/tsconfig.json) but excludes test files and other unneeded type definitions.
+
+## Working on Turbopack, WASM, and other Rust code
+
+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](https://www.rust-lang.org/tools/install) and run `pnpm swc-build-native`.
+
+If you want to test out the wasm build locally, you will need to [install wasm-pack](https://rustwasm.github.io/wasm-pack/installer/). 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`.

contributing/core/developing-using-local-app.md

@@ -0,0 +1,52 @@
+# Developing Using Your Local Version of Next.js
+
+There are two options to develop with your local version of the codebase:
+
+## Develop inside the monorepo
+
+This will use the version of `next` built inside of the Next.js monorepo. You can also let `pnpm dev` run in a separate terminal. This will let you make changes to Next.js at the same time (note that some changes might require re-running `pnpm next-with-deps` or `pnpm next`).
+
+If your app does not have dependencies, you can create a directory inside the monorepo (eg.: `dev-app`) and run `pnpm next ./dev-app` without creating a `package.json` file.
+
+If you already have an app and it has dependencies, you can follow these steps:
+
+1. Move your app inside of the Next.js monorepo.
+
+2. Run with `pnpm next-with-deps ./app-path-in-monorepo`.
+
+## Set as a local dependency in `package.json`
+
+1. Run `pnpm dev` in the background in the Next.js monorepo.
+
+2. In your app's root directory, run:
+
+   ```sh
+   pnpm add ./path/to/next.js/{packages/next,node_modules/{react,react-dom}}
+   ```
+
+   to re-install all of the dependencies and point `next`, `react` and `react-dom` to the monorepo versions.
+
+   Note that Next.js will be copied from the locally compiled version as opposed to being downloaded from the NPM registry.
+
+3. Run your application as you normally would.
+
+### Troubleshooting
+
+- 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.
+
+```json
+{
+  "optionalDependencies": {
+    "@next/swc-linux-x64-gnu": "canary",
+    "@next/swc-win32-x64-msvc": "canary",
+    "@next/swc-darwin-x64": "canary",
+    "@next/swc-darwin-arm64": "canary"
+  }
+}
+```

contributing/core/developing.md

@@ -0,0 +1,132 @@
+# Developing
+
+- The development branch is `canary`.
+- All pull requests should be opened against `canary`.
+- The changes on the `canary` branch are published to the `@canary` tag on npm regularly.
+
+## Dependencies
+
+- Install Rust and Cargo via [rustup](https://rustup.rs).
+- Install the [GitHub CLI](https://github.com/cli/cli#installation).
+- Enable pnpm:
+  ```
+  corepack enable pnpm
+  ```
+- (Linux) Install LLD (the LLVM linker) and Clang (used by `rust-rocksdb`):
+  ```
+  sudo apt install lld clang
+  ```
+
+## Local Development
+
+1. Clone the Next.js repository (download only recent commits for faster clone):
+   ```
+   gh repo clone vercel/next.js -- --filter=blob:none --branch canary --single-branch
+   ```
+1. Create a new branch:
+   ```
+   git checkout -b MY_BRANCH_NAME origin/canary
+   ```
+1. Install the dependencies with:
+   ```
+   pnpm install
+   ```
+1. Start developing and watch for code changes:
+   ```
+   pnpm dev
+   ```
+1. 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._
+1. When your changes are finished, commit them to the branch:
+   ```
+   git add .
+   git commit -m "DESCRIBE_YOUR_CHANGES_HERE"
+   ```
+1. To open a pull request you can use the GitHub CLI which automatically forks and sets up a remote branch. Follow the prompts when running:
+   ```
+   gh pr create
+   ```
+
+For instructions on how to build a project with your local version of the CLI,
+see **[Developing Using Your Local Version of Next.js](./developing-using-local-app.md)** as linking the package is not sufficient to develop locally.
+
+## Testing a local Next.js version on an application
+
+Since Turbopack doesn't support symlinks when pointing outside of the workspace directory, it can be difficult to develop against a local Next.js version. Neither `pnpm link` nor `file:` imports quite cut it. An alternative is to pack the Next.js version you want to test into a tarball and add it to the pnpm overrides of your test application. The following script will do it for you:
+
+```bash
+pnpm pack-next --tar && pnpm unpack-next path/to/project
+```
+
+Or without running the build:
+
+```bash
+pnpm pack-next --no-js-build --tar && pnpm unpack-next path/to/project
+```
+
+Without going through a tarball (only works if you've added the overrides from `pack-next`):
+
+```bash
+pnpm patch-next path/to/project
+```
+
+Supports the same arguments:
+
+```bash
+pnpm patch-next --no-js-build path/to/project
+```
+
+### Explanation of the scripts
+
+```bash
+# Generate a tarball of the Next.js version you want to test
+$ pnpm pack-next --tar
+
+# You can also pass any cargo argument to the script
+
+# To skip the `pnpm i` and `pnpm build` steps in next.js (e. g. if you are running `pnpm dev`)
+$ pnpm pack-next --no-js-build
+```
+
+Afterwards, you'll need to unpack the tarball into your test project. You can either manually edit the `package.json` to point to the new tarballs (see the stdout from `pack-next` script), or you can automatically unpack it with:
+
+```bash
+# Unpack the tarballs generated with pack-next into project's node_modules
+$ pnpm unpack-next path/to/project
+```
+
+## Developing the Dev Overlay
+
+The dev overlay is a feature of Next.js that allows you to see the internal state of the app including the errors. To learn more about contributing to the dev overlay, see the [Dev Overlay README.md](../../packages/next/src/client/components/react-dev-overlay/README.md).
+
+## `NODE_ENV` vs `__NEXT_DEV_SERVER`
+
+Both `next dev` and `next build --debug-prerender` produce bundles with `NODE_ENV=development`. Use `process.env.__NEXT_DEV_SERVER` to distinguish between them:
+
+- `process.env.NODE_ENV !== 'production'` — code that should exist in dev bundles but be eliminated from prod bundles. This is a build-time check.
+- `process.env.__NEXT_DEV_SERVER` — code that should only run with the dev server (`next dev`), not during `next build --debug-prerender` or `next start`.
+
+## Recover disk space
+
+Rust builds quickly add up to a lot of disk space, you can clean up old artifacts with this command:
+
+```bash
+pnpm sweep
+```
+
+It will also clean up other caches (pnpm store, cargo, etc.) and run `git gc` for you.
+
+### MacOS disk compression
+
+If you want to automatically use APFS disk compression on macOS for `node_modules/` and `target/` you can install a launch agent with:
+
+```bash
+./scripts/LaunchAgents/install-macos-agents.sh
+```
+
+Or run it manually with:
+
+```bash
+./scripts/macos-compress.sh
+```

contributing/core/testing.md

@@ -0,0 +1,219 @@
+# Testing
+
+## Running tests
+
+Before you start to run tests, you need to [build the project first](./building.md):
+
+```bash
+pnpm build
+```
+
+We recommend running the tests in a specific directory pattern.
+
+For example, running one test in the production test suite:
+
+Running tests in the `test/e2e/app-dir/app` test suite in production mode (`next build` and `next start`):
+
+```sh
+pnpm test-start test/e2e/app-dir/app/
+```
+
+Running tests in the `test/e2e/app-dir/app` test suite in development mode (`next dev`):
+
+```sh
+pnpm test-dev test/e2e/app-dir/app/
+```
+
+When the test runs, it will open the browser in the background by default, you won't see the browser window.
+
+When you want to debug a particular test you can replace
+`pnpm test-start` with `pnpm testonly-start` to see the browser window open.
+
+```sh
+pnpm testonly-start test/e2e/app-dir/app/
+```
+
+**End-to-end (e2e)** tests are run in complete isolation from the repository.
+When you run an `test/e2e`, `test/production`, or `test/development` tests,
+a local version of Next.js will be created inside your system's temp folder (e.g. /tmp),
+which is then linked to an isolated version of the application.
+A server is started on a random port, against which the tests will run.
+After all tests have finished, the server is destroyed and all remaining files are deleted from the temp folder.
+All of this logic is handled by `nextTestSetup` automatically.
+
+## Writing tests for Next.js
+
+### Getting Started
+
+You can set up a new test using `pnpm new-test` which will start from a template related to the test type.
+
+### Test Types in Next.js
+
+- e2e: Runs against `next dev`, `next start`, and deployed to Vercel.
+- development: Runs against `next dev`.
+- production: Runs against `next start`.
+- integration: Historical location of tests.
+  Runs misc checks and modes.
+  Ideally, we don't add new test suites here anymore as these tests are not isolated from the monorepo.
+- unit: Very fast tests that should run without a browser or run `next` and should be testing a specific utility.
+
+For the e2e, development, and production tests the `nextTestSetup` utility should be used.
+An example is available [here](../../test/e2e/example.txt).
+This creates an isolated Next.js installation
+to ensure nothing in the monorepo is relied on accidentally causing incorrect tests.
+`pnpm new-test` automatically uses `nextTestSetup`
+
+All new test suites should be written in TypeScript either `.ts` (or `.tsx` for unit tests).
+This will help ensure we catch smaller issues in tests that could cause flaky or incorrect tests.
+
+If a test suite already exists that relates closely to the item being tested
+(e.g., hash navigation relates to existing navigation test suites),
+the new checks can be added to the existing test suite.
+
+### Best Practices
+
+- When checking for a condition that might take time,
+  ensure it is waited for either using the browser `waitForElement` or using the `check` util in `next-test-utils`.
+- When applying a fix, ensure the test fails without the fix.
+  This makes sure the test will properly catch regressions.
+
+### Helpful environment variables
+
+Some test-specific environment variables can be used to help debug isolated tests better,
+these can be leveraged by prefixing the `pnpm test` command.
+
+- When investigating failures in isolated tests you can use
+  `NEXT_TEST_SKIP_CLEANUP=1` to prevent deleting the temp folder created for the test,
+  then you can run `pnpm debug` while inside the temp folder to debug the fully set-up test project.
+- You can also use `NEXT_SKIP_ISOLATE=1` if the test doesn't need to be installed to debug,
+  and it will run inside the Next.js repo instead of the temp directory,
+  this can also reduce test times locally but is not compatible with all tests.
+- The `NEXT_TEST_MODE` env variable allows toggling specific test modes for the `e2e` folder,
+  it can be used when not using `pnpm test-dev` or `pnpm test-start` directly.
+  Valid test modes can be seen here:
+  https://github.com/vercel/next.js/blob/aa664868c102ddc5adc618415162d124503ad12e/test/lib/e2e-utils.ts#L46
+- Use `NEXT_TEST_DEPLOY_URL` with `pnpm test-deploy` to skip the Vercel deploy step and run
+  deploy-mode assertions against an existing deployment URL.
+- You can use `NEXT_TEST_PREFER_OFFLINE=1` while testing to configure the package manager to include the
+  [`--prefer-offline`](https://pnpm.io/cli/install#--prefer-offline) argument during test setup.
+  This is helpful when running tests in internet-restricted environments such as planes or public Wi-Fi.
+
+### Debugging
+
+When tests are run in CI and a test failure occurs,
+we attempt to capture traces of the playwright run to make debugging the failure easier.
+A test-trace artifact should be uploaded after the workflow completes which can be downloaded, unzipped,
+and then inspected with `pnpm playwright show-trace ./path/to/trace`
+
+To attach the chrome debugger to next the easiest approach is to modify the `createNext` call in your test to pass `--inspect` to next.
+
+```js
+const next = await createNext({
+  ...
+  startArgs: =['--inspect'],
+})
+```
+
+Consider also sett `NEXT_E2E_TEST_TIMEOUT=0`
+
+To debug the test process itself you need to pass the `inspect` flag to the node process running jest. e.g. `IS_TURBOPACK_TEST=1 TURBOPACK_DEV=1 NEXT_TEST_MODE=dev node --inspect node_modules/jest/bin/jest.js ...`
+
+### Profiling tests
+
+Add `NEXT_TEST_TRACE=1` to enable test profiling. It's useful for improving our testing infrastructure.
+
+### Testing Turbopack
+
+To run the test suite using Turbopack, you can use the `-turbo` version of the npm script:
+
+```sh
+pnpm test-dev-turbo test/e2e/app-dir/app/
+```
+
+If you want to run a test again both Turbopack and Webpack, use Jest's `--projects` flag:
+
+```sh
+pnpm test-dev test/e2e/app-dir/app/ --projects jest.config.*
+```
+
+## Integration testing outside the repository with local builds
+
+You can locally generate builds for each package in this repository with:
+
+```bash
+pnpm pack-next
+```
+
+You can automatically apply modifications to `package.json` by specifying your project directory:
+
+```bash
+pnpm pack-next --project ~/shadcn-ui/apps/www/
+```
+
+This will find and modify parent workspaces when relevant. These automatic overrides should work
+with `npm` and `pnpm`. There are known issues preventing it from working with `bun` and `yarn`.
+
+Flags can be passed to `napi`'s CLI, separated by an argument separator (`--`). For example:
+
+```bash
+pnpm pack-next --project ~/my-project/ -- --release
+```
+
+See `pnpm pack-next --help` for more details.
+
+### Locally creating tarballs
+
+You can create tarballs with:
+
+```bash
+pnpm pack-next --tar
+```
+
+The tarballs will be written to a `tarballs` directory in the root of the repository, and you will
+be shown information about how to use these tarballs in a project by modifying the workspace
+`package.json` file.
+
+On Linux, this generates stripped `@next/swc` binaries to avoid exceeding 2 GiB, [which is
+known to cause problems with `pnpm`](https://github.com/libuv/libuv/pull/1501). That behavior can be
+overridden with `--compress objcopy-zstd` on Linux (which is slower, but retains debuginfo).
+
+These tarballs can be extracted directly into a project's `node_modules` directory (bypassing the
+package manager) by using:
+
+```bash
+pnpm unpack-next ~/shadcn-ui
+```
+
+However, this is not typically recommended, as installing using the package manager is safer.
+
+## Integration testing outside the repository with preview builds
+
+Every branch build will create a tarball for each package in this repository<sup>1</sup> that can be used in external repositories.
+
+You can use this preview build in other packages by using a https://vercel-packages.vercel.app URL instead of a version in the `package.json`.
+Dependencies are automatically rewritten to use the same commit SHA as the package you are using.
+For example, if you install `next` from commit `abc`, `next` will have a dependency on `@next/env` at commit `abc` **and** use `next-swc` from commit `abc` as well.
+
+To use `next` from a specific commit (full SHA required):
+
+```json
+{
+  "dependencies": {
+    "next": "https://vercel-packages.vercel.app/next/commits/188f76947389a27e9bcff8ebf9079433679256a7/next"
+  }
+}
+```
+
+or, to use `next` from a specific Pull Request (PR number required):
+
+```json
+{
+  "dependencies": {
+    "next": "https://vercel-packages.vercel.app/next/prs/66445/next"
+  }
+}
+```
+
+<sup>1</sup> Not all native packages are built automatically.
+`build-and-deploy` excludes slow, rarely used native variants of `next-swc`.
+To force a build of all packages, you can [trigger `build-and-deploy` manually](https://github.com/vercel/next.js/actions/workflows/build_and_deploy.yml) (i.e. `workflow_dispatch`).

contributing/core/vscode-debugger.md

@@ -0,0 +1,27 @@
+# Using the VS Code Debugger
+
+## Debug configurations
+
+The Next.js monorepo provides configurations in the [`.vscode/launch.json`](../../.vscode/launch.json) file to help you [debug Next.js from VS Code](https://code.visualstudio.com/docs/editor/debugging).
+
+The common configurations are:
+
+- **Launch app**: Run `next dev`, `next build`, or `next start` in a directory of your choice, with an attached debugger.
+- **Launch current directory**: Run `next dev`, `next build`, or `next start` in the directory of the currently active file, with an attached debugger.
+- **Run e2e test**: Run an e2e test using the currently active file, with an attached debugger.
+
+### Run a specific app
+
+Any Next.js app inside the monorepo can be debugged with these configurations.
+
+1. Use the status bar, or the "Run and Debug" item in the Activity Bar, to select the "Launch app" launch configuration.
+2. Enter the app dirname, e.g. `examples/hello-world` or `test/e2e/app-dir/app`.
+3. Select the `next` command from the presented options (`dev`, `build`, or `start`).
+
+To see the changes you make to the Next.js codebase during development, you can run `pnpm dev` in the root directory, which will watch for file changes in `packages/next` and recompile the Next.js source code on any file saves.
+
+## Breakpoints
+
+When developing/debugging Next.js, you can set breakpoints anywhere in the `packages/next` source code that will stop the debugger at certain locations so you can examine the behavior. Read more about [breakpoints in the VS Code documentation](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_breakpoints).
+
+To ensure that the original names are displayed in the "Variables" section, build the Next.js source code with `NEXT_SERVER_NO_MANGLE=1`. This is automatically applied when using `pnpm dev`.