refactor: split up CONTRIBUTING.md

.vscode/launch.json

@@ -9,92 +9,81 @@
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}",
-      "runtimeExecutable": "yarn",
-      "runtimeArgs": ["run", "debug-react-exp", "dev", "test/e2e/app-dir/app"],
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["debug-react-exp", "dev", "test/e2e/app-dir/app"],
       "skipFiles": ["<node_internals>/**"],
-      "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"],
-      "port": 9229,
       "env": {
-        "NEXT_PRIVATE_LOCAL_WEBPACK5": "1"
+        "NEXT_PRIVATE_LOCAL_webpack": "1"
       }
     },
     {
       "name": "Launch app development",
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}",
-      "runtimeExecutable": "yarn",
-      "runtimeArgs": ["run", "debug", "dev", "bench/nested-deps"],
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["debug", "dev", "examples/hello-world"],
       "skipFiles": ["<node_internals>/**"],
-      "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"],
-      "port": 9229,
       "env": {
-        "NEXT_PRIVATE_LOCAL_WEBPACK5": "1"
+        "NEXT_PRIVATE_LOCAL_webpack": "1"
       }
     },
     {
       "name": "Launch app build",
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}",
-      "runtimeExecutable": "yarn",
-      "runtimeArgs": ["run", "debug", "build", "bench/nested-deps"],
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["debug", "build", "examples/hello-world"],
       "skipFiles": ["<node_internals>/**"],
-      "port": 9229,
-      "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"],
       "env": {
-        "NEXT_PRIVATE_LOCAL_WEBPACK5": "1"
+        "NEXT_PRIVATE_LOCAL_webpack": "1"
       }
     },
     {
-      "name": "Launch app build trace jaeger",
+      "name": "Launch app production",
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}",
-      "runtimeExecutable": "yarn",
-      "runtimeArgs": ["run", "clean-trace-jaeger"],
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["debug", "start", "examples/hello-world"],
       "skipFiles": ["<node_internals>/**"],
-      "port": 9229,
-      "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"],
       "env": {
-        "NEXT_PRIVATE_LOCAL_WEBPACK5": "1"
+        "NEXT_PRIVATE_LOCAL_webpack": "1"
       }
     },
     {
-      "name": "Launch app production",
+      "name": "Launch current directory in development",
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}",
-      "runtimeExecutable": "yarn",
-      "runtimeArgs": ["run", "debug", "start", "bench/nested-deps"],
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["debug", "dev", "${fileDirname}"],
       "skipFiles": ["<node_internals>/**"],
-      "port": 9229,
       "env": {
-        "NEXT_PRIVATE_LOCAL_WEBPACK5": "1"
+        "NEXT_PRIVATE_LOCAL_webpack": "1"
       }
     },
     {
+      "name": "Launch app build trace jaeger",
       "type": "node",
-      "request": "attach",
-      "name": "Attach to existing debugger",
-      "port": 9229,
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["clean-trace-jaeger"],
       "skipFiles": ["<node_internals>/**"],
-      "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"],
       "env": {
-        "NEXT_PRIVATE_LOCAL_WEBPACK5": "1"
+        "NEXT_PRIVATE_LOCAL_webpack": "1"
       }
     },
     {
-      "name": "Launch this example",
       "type": "node",
-      "request": "launch",
-      "cwd": "${workspaceFolder}",
-      "runtimeExecutable": "yarn",
-      "runtimeArgs": ["run", "debug", "dev", "${fileDirname}"],
-      "skipFiles": ["<node_internals>/**"],
+      "request": "attach",
+      "name": "Attach to existing debugger",
       "port": 9229,
+      "skipFiles": ["<node_internals>/**"],
       "env": {
-        "NEXT_PRIVATE_LOCAL_WEBPACK5": "1"
+        "NEXT_PRIVATE_LOCAL_webpack": "1"
       }
     }
   ]

bench/nested-deps/package.json

@@ -1,11 +1,11 @@
 {
   "scripts": {
     "prepare": "rimraf components && mkdir components && node ./fuzzponent.js -d 2 -s 206 -o components",
-    "dev": "cross-env NEXT_PRIVATE_LOCAL_WEBPACK5=1 node ../../node_modules/next/dist/bin/next dev",
-    "build": "cross-env NEXT_PRIVATE_LOCAL_WEBPACK5=1 node ../../node_modules/next/dist/bin/next build",
-    "start": "cross-env NEXT_PRIVATE_LOCAL_WEBPACK5=1 node ../../node_modules/next/dist/bin/next start",
+    "dev": "cross-env NEXT_PRIVATE_LOCAL_webpack=1 node ../../node_modules/next/dist/bin/next dev",
+    "build": "cross-env NEXT_PRIVATE_LOCAL_webpack=1 node ../../node_modules/next/dist/bin/next build",
+    "start": "cross-env NEXT_PRIVATE_LOCAL_webpack=1 node ../../node_modules/next/dist/bin/next start",
     "dev-nocache": "rimraf .next && yarn dev",
-    "dev-cpuprofile-nocache": "rimraf .next && cross-env NEXT_PRIVATE_LOCAL_WEBPACK5=1 node --cpu-prof ../../node_modules/next/dist/bin/next",
+    "dev-cpuprofile-nocache": "rimraf .next && cross-env NEXT_PRIVATE_LOCAL_webpack=1 node --cpu-prof ../../node_modules/next/dist/bin/next",
     "build-nocache": "rimraf .next && yarn build"
   },
   "devDependencies": {

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

@@ -16,49 +16,23 @@ If you already have an app and it has dependencies, you can follow these steps:
 
 ## Set as a local dependency in package.json
 
-1. In your app's `package.json`, replace:
+1. Run `pnpm dev` in the background in the Next.js monorepo.
 
-   ```json
-   "next": "<version>",
-   "react": "<version>",
-   "react-dom": "<version>",
-   ```
-
-   with:
-
-   ```json
-   "next": "link:/path/to/next.js/packages/next",
-   "react": "link:/path/to/next.js/node_modules/react",
-   "react-dom": "link:/path/to/next.js/node_modules/react-dom"
-   ```
-
-2. In your app's root directory, make sure to remove `next` from `node_modules` with:
+2. In your app's root directory, run:
 
    ```sh
-   rm -rf ./node_modules/next
+   pnpm add ./path/to/next.js/{packages/next,node_modules/{react,react-dom}}
    ```
 
-3. In your app's root directory, run:
+   to re-install all of the dependencies and point `next`, `react` and `react-dom` to the monorepo versions.
 
-   ```sh
-   pnpm i
-   ```
+   Note that Next.js will be copied from the locally compiled version as opposed to being downloaded from the NPM registry.
 
-   to re-install all of the dependencies.
-
-   Note that Next will be copied from the locally compiled version as opposed to being downloaded from the NPM registry.
-
-4. Run your application as you normally would.
-
-5. To update your app's dependencies, after you've made changes to your local `next` repository. In your app's root directory, run:
-
-   ```sh
-   pnpm install --force
-   ```
+3. Run your application as you normally would.
 
 ### Troubleshooting
 
-- If you see the below error while running `pnpm dev` with next:
+- 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

contributing/core/testing.md

@@ -2,51 +2,45 @@
 
 ## Running tests
 
-We recommend running the tests in headless mode (with the browser windows hidden) and with a specific directory pattern (`--testPathPattern`) or test name (`-t`) which ensures only a small part of the test suite is run locally:
+We recommend running the tests in headless mode (with the browser windows hidden) and with a specific directory pattern and/or test name (`-t`) which ensures only a small part of the test suite is run locally:
 
 For example, running one test in the production test suite:
 
 ````
 Running one test in the `test/integration/production` test suite:
 
 ```sh
-pnpm test --testPathPattern "test/integration/production" -t "should allow etag header support"
+pnpm test -- test/integration/production -t "should allow etag header support"
 ````
 
 Running all tests in the `test/integration/production` test suite:
 
 ```sh
-pnpm test --testPathPattern "test/integration/production"
-```
-
-Running all tests (⚠️ not recommended locally):
-
-```sh
-pnpm test
+pnpm test test/integration/production
 ```
 
 When you want to debug a particular test you can replace `pnpm test` with `pnpm testonly` to opt out of the headless browser.
 When the test runs it will open the browser that is in the background by default, allowing you to inspect what is on the screen.
 
 ```sh
-pnpm testonly --testPathPattern "test/integration/production" -t "should allow etag header support"
+pnpm testonly -- test/integration/production -t "should allow etag header support"
 ```
 
 ## Writing tests for Next.js
 
 ### Getting Started
 
-You can set up a new test using `pnpnm new-test` which will start from a template related to the test type.
+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: These tests will run against `next dev`, `next start`, and deployed to Vercel
-- development: These tests only run against `next dev`
-- production: These tests will run against `next start`.
-- integration: These tests run misc checks and modes and it is where tests were added historically. Ideally, we don't add new test suites here anymore as these tests are not isolated from the monorepo.
-- unit: These are very fast tests that should run without a browser or run `next` and should be testing a specific utility.
+- 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, production, and development tests the `createNext` utility should be used and an example is available [here](../../test/e2e/example.txt). This creates an isolated Next.js install to ensure nothing in the monorepo is relied on accidentally causing incorrect tests.
+For the e2e, development, and production tests the `createNext` utility should be used and an example is available [here](../../test/e2e/example.txt). This creates an isolated Next.js install to ensure nothing in the monorepo is relied on accidentally causing incorrect tests.
 
 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 flakey or incorrect tests.
 

contributing/core/vscode-debugger.md

@@ -1,3 +1,27 @@
 # Using the VS Code Debugger
 
-TODO
+## 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 development: Run `next dev` with an attached debugger
+- Launch app build: Run `next build` with an attached debugger
+- Launch app production: Run `next start` with an attached debugger
+
+### Run a specific app
+
+Any Next.js app inside the monorepo can be debugged with these configurations. For example to run "Launch app development" against `examples/hello-world`:
+
+1. Open the [`.vscode/launch.json`](../../.vscode/launch.json) file.
+2. Find the configuration "Launch app development".
+3. Edit the `runtimeArgs` array's last item to be `"examples/hello-world"`.
+4. Save the file.
+5. Now you can start the debugger and it will run against the `examples/hello-world` app!
+
+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).