From b118a4870979a3ac8818983b0b7ba15c5fdba2d0 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 20:20:09 +0100 Subject: [PATCH 01/27] Split contributing.md into directory --- contributing.md | 344 +----------------- contributing/core/adding-error-links.md | 16 + contributing/core/building.md | 15 + .../core/developing-using-local-app.md | 70 ++++ contributing/core/developing.md | 42 +++ contributing/core/testing.md | 27 ++ contributing/docs/adding-documentation.md | 40 ++ contributing/examples/adding-examples.md | 57 +++ contributing/examples/run-example-apps.md | 22 ++ contributing/maintenance/linting.md | 13 + contributing/maintenance/publishing.md | 3 + contributing/maintenance/triaging.md | 21 ++ 12 files changed, 341 insertions(+), 329 deletions(-) create mode 100644 contributing/core/adding-error-links.md create mode 100644 contributing/core/building.md create mode 100644 contributing/core/developing-using-local-app.md create mode 100644 contributing/core/developing.md create mode 100644 contributing/core/testing.md create mode 100644 contributing/docs/adding-documentation.md create mode 100644 contributing/examples/adding-examples.md create mode 100644 contributing/examples/run-example-apps.md create mode 100644 contributing/maintenance/linting.md create mode 100644 contributing/maintenance/publishing.md create mode 100644 contributing/maintenance/triaging.md diff --git a/contributing.md b/contributing.md index 6238e972f4bf..715ccd6b0e1f 100644 --- a/contributing.md +++ b/contributing.md @@ -8,339 +8,25 @@ - To contribute to [our examples](examples), please see [Adding examples](#adding-examples) below. - Before jumping into a PR be sure to search [existing PRs](https://github.com/vercel/next.js/pulls) or [issues](https://github.com/vercel/next.js/issues) for an open or closed item that relates to your submission. -## Developing +## Core -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. +- [Adding Error Links](./contributing/core/adding-error-links.md) +- [Building](./contributing/core/building.md) +- [Developing Using Local App](./contributing/core/developing-using-local-app.md) +- [Developing](./contributing/core/developing.md) +- [Testing](./contributing/core/testing.md) -To develop locally: +## Documentation -1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your - own GitHub account and then - [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device. +- [Adding Documentation](./contributing/docs/adding-documentation.md) - If you don't need the whole git history, you can clone with depth 1 to reduce the download size (~1.6GB): +## Examples - ```sh - git clone --depth=1 https://github.com/vercel/next.js - ``` +- [Adding Examples](./contributing/examples/adding-examples.md) +- [Run Example Apps](./contributing/examples/run-example-apps.md) -2. Create a new branch: - ``` - git checkout -b MY_BRANCH_NAME - ``` -3. Enable pnpm: - ``` - corepack enable pnpm - ``` -4. Install the dependencies with: - ``` - pnpm install - ``` -5. Start developing and watch for code changes: - ``` - pnpm dev - ``` -6. In a new terminal, run `pnpm types` to compile declaration files from - TypeScript. +## Maintenance - _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](#developing-with-your-local-version-of-nextjs)** -below. (Naively linking the binary is not sufficient to develop locally.) - -## Building - -You can build the project, including all type definitions, with: - -```bash -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](https://www.rust-lang.org/tools/install) 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](https://rustwasm.github.io/wasm-pack/installer/). Run `pnpm --filter=@next/swc build-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`. - -## Testing - -See the [testing readme](./test/readme.md) for information on writing tests. - -### Running tests - -```sh -pnpm testonly -``` - -If you would like to run the tests in headless mode (with the browser windows hidden) you can do - -```sh -pnpm testheadless -``` - -Running a specific test suite (e.g. `production`) inside of the `test/integration` directory: - -```sh -pnpm testonly --testPathPattern "production" -``` - -Running one test in the `production` test suite: - -```sh -pnpm testonly --testPathPattern "production" -t "should allow etag header support" -``` - -### Linting - -To check the formatting of your code: - -```sh -pnpm lint -``` - -If you get errors, you can fix them with: - -```sh -pnpm lint-fix -``` - -### Running the example apps - -Running examples can be done with: - -```sh -pnpm next ./examples/basic-css/ -``` - -To figure out which pages are available for the given example, you can run: - -```sh -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{} \ -) -``` - -## Developing with your local version of Next.js - -There are two options to develop with your local version of the codebase: - -### Set as a local dependency in package.json - -1. In your app's `package.json`, replace: - - ```json - "next": "", - ``` - - with: - - ```json - "next": "file:/path/to/next.js/packages/next", - ``` - -2. In your app's root directory, make sure to remove `next` from `node_modules` with: - - ```sh - rm -rf ./node_modules/next - ``` - -3. In your app's root directory, run: - - ```sh - 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. - -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 - ``` - -#### 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" -}, -``` - -### Develop inside the monorepo - -1. Move your app inside of the Next.js monorepo. - -2. 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). - -## Updating documentation paths - -Our documentation currently leverages a [manifest file](/docs/manifest.json) 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](/docs) that points to the new location in the folder e.g. `/docs/some-url.md` - -Example of moving documentation file: - -Before: - -```json -[ - { - "path": "/docs/original.md", - "title": "Hello world" - } -] -``` - -After: - -```json -[ - { - "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. - -## Adding warning/error descriptions - -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: - -1. Run `pnpm new-error` which will create the error document and update the manifest automatically. -2. Add the following url to your warning/error: - `https://nextjs.org/docs/messages/`. - - For example, to link to `errors/api-routes-static-export.md` you use the url: - `https://nextjs.org/docs/messages/api-routes-static-export` - -## Adding examples - -When you add an example to the [examples](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` in `package.json`) -- In `package.json` the version of `next` (and `eslint-config-next`) should be `latest` -- In `package.json` the dependency versions should be up-to-date -- Use `export default function` for page components and API Routes instead of `const`/`let` (The exception is if the page has `getInitialProps`, in which case [`NextPage`](https://nextjs.org/docs/api-reference/data-fetching/get-initial-props#typescript) 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` and `Description`. -- Examples should be TypeScript first, if possible. -- Omit the `name` and `version` fields from your `package.json`. -- Ensure all your dependencies are up to date. -- Ensure you’re using [`next/image`](https://nextjs.org/docs/api-reference/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. - -````markdown -# 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)). -```` - -## Publishing - -Repository maintainers can use `yarn publish-canary` to publish a new version of all packages to npm. - -## Triaging - -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 discussion](https://github.com/vercel/next.js/discussions/categories/ideas) -- `template: bug` - unverified issue with Next.js itself, or one of the examples in the [`examples`](https://github.com/vercel/next.js/tree/canary/examples) folder -- `template: 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](https://github.com/vercel/next.js/discussions/categories/help) - -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). +- [Linting](./contributing/maintenance/linting.md) +- [Publishing](./contributing/maintenance/publishing.md) +- [Triaging](./contributing/maintenance/triaging.md) diff --git a/contributing/core/adding-error-links.md b/contributing/core/adding-error-links.md new file mode 100644 index 000000000000..6778ca1ea9fe --- /dev/null +++ b/contributing/core/adding-error-links.md @@ -0,0 +1,16 @@ +# Adding Warning and Error Descriptions + +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: + +1. Run `pnpm new-error` which will create the error document and update the manifest automatically. +2. Add the following url to your warning/error: + `https://nextjs.org/docs/messages/`. + + For example, to link to `errors/api-routes-static-export.md` you use the url: + `https://nextjs.org/docs/messages/api-routes-static-export` diff --git a/contributing/core/building.md b/contributing/core/building.md new file mode 100644 index 000000000000..3970b38ff0b1 --- /dev/null +++ b/contributing/core/building.md @@ -0,0 +1,15 @@ +# Building + +You can build the project, including all type definitions, with: + +```bash +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](https://www.rust-lang.org/tools/install) 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](https://rustwasm.github.io/wasm-pack/installer/). Run `pnpm --filter=@next/swc build-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`. diff --git a/contributing/core/developing-using-local-app.md b/contributing/core/developing-using-local-app.md new file mode 100644 index 000000000000..413a6924efdd --- /dev/null +++ b/contributing/core/developing-using-local-app.md @@ -0,0 +1,70 @@ +# Developing With Your Local Version of Next.js + +There are two options to develop with your local version of the codebase: + +### Set as a local dependency in package.json + +1. In your app's `package.json`, replace: + + ```json + "next": "", + ``` + + with: + + ```json + "next": "file:/path/to/next.js/packages/next", + ``` + +2. In your app's root directory, make sure to remove `next` from `node_modules` with: + + ```sh + rm -rf ./node_modules/next + ``` + +3. In your app's root directory, run: + + ```sh + 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. + +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 + ``` + +#### 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" +}, +``` + +### Develop inside the monorepo + +1. Move your app inside of the Next.js monorepo. + +2. 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). diff --git a/contributing/core/developing.md b/contributing/core/developing.md new file mode 100644 index 000000000000..2f589120ede8 --- /dev/null +++ b/contributing/core/developing.md @@ -0,0 +1,42 @@ +# Developing + +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: + +1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your + own GitHub account and then + [clone](https://help.github.com/articles/cloning-a-repository/) 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): + + ```sh + git clone --depth=1 https://github.com/vercel/next.js + ``` + +2. Create a new branch: + ``` + git checkout -b MY_BRANCH_NAME + ``` +3. Enable pnpm: + ``` + corepack enable pnpm + ``` +4. Install the dependencies with: + ``` + pnpm install + ``` +5. Start developing and watch for code changes: + ``` + pnpm dev + ``` +6. 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](#developing-with-your-local-version-of-nextjs)** +below. (Naively linking the binary is not sufficient to develop locally.) diff --git a/contributing/core/testing.md b/contributing/core/testing.md new file mode 100644 index 000000000000..2bd6d9970d8a --- /dev/null +++ b/contributing/core/testing.md @@ -0,0 +1,27 @@ +# Testing + +See the [testing readme](./test/readme.md) for information on writing tests. + +### Running tests + +```sh +pnpm testonly +``` + +If you would like to run the tests in headless mode (with the browser windows hidden) you can do + +```sh +pnpm testheadless +``` + +Running a specific test suite (e.g. `production`) inside of the `test/integration` directory: + +```sh +pnpm testonly --testPathPattern "production" +``` + +Running one test in the `production` test suite: + +```sh +pnpm testonly --testPathPattern "production" -t "should allow etag header support" +``` diff --git a/contributing/docs/adding-documentation.md b/contributing/docs/adding-documentation.md new file mode 100644 index 000000000000..cb7b3614c25b --- /dev/null +++ b/contributing/docs/adding-documentation.md @@ -0,0 +1,40 @@ +# Updating Documentation Paths + +Our documentation currently leverages a [manifest file](/docs/manifest.json) 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](/docs) that points to the new location in the folder e.g. `/docs/some-url.md` + +Example of moving documentation file: + +Before: + +```json +[ + { + "path": "/docs/original.md", + "title": "Hello world" + } +] +``` + +After: + +```json +[ + { + "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. diff --git a/contributing/examples/adding-examples.md b/contributing/examples/adding-examples.md new file mode 100644 index 000000000000..109afbbe32fb --- /dev/null +++ b/contributing/examples/adding-examples.md @@ -0,0 +1,57 @@ +# Adding Examples + +When you add an example to the [examples](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` in `package.json`) +- In `package.json` the version of `next` (and `eslint-config-next`) should be `latest` +- In `package.json` the dependency versions should be up-to-date +- Use `export default function` for page components and API Routes instead of `const`/`let` (The exception is if the page has `getInitialProps`, in which case [`NextPage`](https://nextjs.org/docs/api-reference/data-fetching/get-initial-props#typescript) 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` and `Description`. +- Examples should be TypeScript first, if possible. +- Omit the `name` and `version` fields from your `package.json`. +- Ensure all your dependencies are up to date. +- Ensure you’re using [`next/image`](https://nextjs.org/docs/api-reference/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. + +````markdown +# 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)). +```` diff --git a/contributing/examples/run-example-apps.md b/contributing/examples/run-example-apps.md new file mode 100644 index 000000000000..c95c20cd35a5 --- /dev/null +++ b/contributing/examples/run-example-apps.md @@ -0,0 +1,22 @@ +# Running Example Apps + +Running examples can be done with: + +```sh +pnpm next ./examples/basic-css/ +``` + +To figure out which pages are available for the given example, you can run: + +```sh +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{} \ +) +``` diff --git a/contributing/maintenance/linting.md b/contributing/maintenance/linting.md new file mode 100644 index 000000000000..e838d4a0c2f2 --- /dev/null +++ b/contributing/maintenance/linting.md @@ -0,0 +1,13 @@ +# Linting + +To check the formatting of your code: + +```sh +pnpm lint +``` + +If you get errors, you can fix them with: + +```sh +pnpm lint-fix +``` diff --git a/contributing/maintenance/publishing.md b/contributing/maintenance/publishing.md new file mode 100644 index 000000000000..f9796a17d043 --- /dev/null +++ b/contributing/maintenance/publishing.md @@ -0,0 +1,3 @@ +# Publishing + +Repository maintainers can use `yarn publish-canary` to publish a new version of all packages to npm. diff --git a/contributing/maintenance/triaging.md b/contributing/maintenance/triaging.md new file mode 100644 index 000000000000..ab9bfa7e91fe --- /dev/null +++ b/contributing/maintenance/triaging.md @@ -0,0 +1,21 @@ +# Triaging + +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 discussion](https://github.com/vercel/next.js/discussions/categories/ideas) +- `template: bug` - unverified issue with Next.js itself, or one of the examples in the [`examples`](https://github.com/vercel/next.js/tree/canary/examples) folder +- `template: 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](https://github.com/vercel/next.js/discussions/categories/help) + +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). From c148fe25f954b8dba4dbb103d9b0d6f91165998f Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 20:45:28 +0100 Subject: [PATCH 02/27] Update linting --- contributing/maintenance/linting.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/contributing/maintenance/linting.md b/contributing/maintenance/linting.md index e838d4a0c2f2..1b6d5d2ac800 100644 --- a/contributing/maintenance/linting.md +++ b/contributing/maintenance/linting.md @@ -1,13 +1,29 @@ # Linting -To check the formatting of your code: +The Next.js repository runs [ESLint](TODO) and [Prettier](TODO) to lint and format all code. + +To lint all code you can run: ```sh pnpm lint ``` -If you get errors, you can fix them with: +If you get errors, you can run the ESLint and Prettier auto-fix using: ```sh pnpm lint-fix ``` + +Not all rules can be auto-fixed, those require manual changes. + +## ESLint + +You can find the enabled rules in the [ESLint config](../../.eslintrc.json). + +We recommend installing the [ESLint plugin for VS Code](TODO). + +## Prettier + +We recommend installing the [Prettier plugin for VS Code](TODO). + +You can find the format configuration in the [Prettier config](../../.prettierrc.json). From cf50a2d81a77617fc88d16f9abb2d91549aff566 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 20:45:42 +0100 Subject: [PATCH 03/27] Add information about publishing --- contributing/maintenance/publishing.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/contributing/maintenance/publishing.md b/contributing/maintenance/publishing.md index f9796a17d043..465a7e3b879b 100644 --- a/contributing/maintenance/publishing.md +++ b/contributing/maintenance/publishing.md @@ -1,3 +1,23 @@ # Publishing -Repository maintainers can use `yarn publish-canary` to publish a new version of all packages to npm. +Next.js has two release channels: `stable` and `canary`. + +## Stable + +The stable release is what is installed when you `npm install next`. This channel is used by the majority of Next.js users. + +This channel is published at a regular cadence and follows [semantic versioning](TODO). + +Repository maintainers can publish a new stable version using: `pnpm publish-stable`. + +## Canary + +The canary channel has to be explicitly installed by users through `npm install next@canary`. + +This channel is published early based on the `canary` branch. It holds all changes that are waiting to be published to the stable channel. + +`canary` is used to test the latest features and bugfixes on real-world applications. + +By installing `next@canary` from time to time you can check if your application is affected by any changes that have not been published yet. + +Repository maintainers can publish a new stable version using: `pnpm publish-stable`. From d81f2a738a0aac19c428aa5efac215a58a134611 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 20:46:55 +0100 Subject: [PATCH 04/27] Add note on how version is decided --- contributing/maintenance/publishing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/contributing/maintenance/publishing.md b/contributing/maintenance/publishing.md index 465a7e3b879b..73344938c47f 100644 --- a/contributing/maintenance/publishing.md +++ b/contributing/maintenance/publishing.md @@ -9,6 +9,7 @@ The stable release is what is installed when you `npm install next`. This channe This channel is published at a regular cadence and follows [semantic versioning](TODO). Repository maintainers can publish a new stable version using: `pnpm publish-stable`. +The command will ask what version to publish `major`, `minor`, or `patch`. ## Canary @@ -21,3 +22,4 @@ This channel is published early based on the `canary` branch. It holds all chang By installing `next@canary` from time to time you can check if your application is affected by any changes that have not been published yet. Repository maintainers can publish a new stable version using: `pnpm publish-stable`. +The command will automatically decide the new version tag as it's an increment from the previous version. From 2b4f43732bf4b45302cbc6ef0cf5ec162e1893ae Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 20:53:46 +0100 Subject: [PATCH 05/27] Change order and rename maintenance -> repository --- contributing.md | 19 ++++++++++--------- .../{maintenance => repository}/linting.md | 0 .../{maintenance => repository}/publishing.md | 0 .../repository/pull-request-descriptions.md | 3 +++ .../{maintenance => repository}/triaging.md | 0 5 files changed, 13 insertions(+), 9 deletions(-) rename contributing/{maintenance => repository}/linting.md (100%) rename contributing/{maintenance => repository}/publishing.md (100%) create mode 100644 contributing/repository/pull-request-descriptions.md rename contributing/{maintenance => repository}/triaging.md (100%) diff --git a/contributing.md b/contributing.md index 715ccd6b0e1f..2a1ee07b184a 100644 --- a/contributing.md +++ b/contributing.md @@ -8,13 +8,20 @@ - To contribute to [our examples](examples), please see [Adding examples](#adding-examples) below. - Before jumping into a PR be sure to search [existing PRs](https://github.com/vercel/next.js/pulls) or [issues](https://github.com/vercel/next.js/issues) for an open or closed item that relates to your submission. +## Repository + +- [Pull Request Descriptions](./contributing/repository/pull-request-descriptions.md) +- [Linting](./contributing/repository/linting.md) +- [Publishing](./contributing/repository/publishing.md) +- [Triaging](./contributing/repository/triaging.md) + ## Core -- [Adding Error Links](./contributing/core/adding-error-links.md) -- [Building](./contributing/core/building.md) -- [Developing Using Local App](./contributing/core/developing-using-local-app.md) - [Developing](./contributing/core/developing.md) +- [Building](./contributing/core/building.md) - [Testing](./contributing/core/testing.md) +- [Adding Error Links](./contributing/core/adding-error-links.md) +- [Developing Using Local App](./contributing/core/developing-using-local-app.md) ## Documentation @@ -24,9 +31,3 @@ - [Adding Examples](./contributing/examples/adding-examples.md) - [Run Example Apps](./contributing/examples/run-example-apps.md) - -## Maintenance - -- [Linting](./contributing/maintenance/linting.md) -- [Publishing](./contributing/maintenance/publishing.md) -- [Triaging](./contributing/maintenance/triaging.md) diff --git a/contributing/maintenance/linting.md b/contributing/repository/linting.md similarity index 100% rename from contributing/maintenance/linting.md rename to contributing/repository/linting.md diff --git a/contributing/maintenance/publishing.md b/contributing/repository/publishing.md similarity index 100% rename from contributing/maintenance/publishing.md rename to contributing/repository/publishing.md diff --git a/contributing/repository/pull-request-descriptions.md b/contributing/repository/pull-request-descriptions.md new file mode 100644 index 000000000000..a04cf26e3a6f --- /dev/null +++ b/contributing/repository/pull-request-descriptions.md @@ -0,0 +1,3 @@ +# Pull Request Descriptions + +TODO diff --git a/contributing/maintenance/triaging.md b/contributing/repository/triaging.md similarity index 100% rename from contributing/maintenance/triaging.md rename to contributing/repository/triaging.md From 0c28eb0f80342fbefccfff4a731c13c3ae8cf5f8 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 21:08:04 +0100 Subject: [PATCH 06/27] Add GitHub CLI recommendation instead of fork link --- contributing.md | 11 +++-- .../core/developing-using-local-app.md | 2 +- contributing/core/developing.md | 44 ++++++++++--------- ...hing.md => release-channels-publishing.md} | 2 +- 4 files changed, 30 insertions(+), 29 deletions(-) rename contributing/repository/{publishing.md => release-channels-publishing.md} (97%) diff --git a/contributing.md b/contributing.md index 2a1ee07b184a..d8fd2b4a2896 100644 --- a/contributing.md +++ b/contributing.md @@ -2,18 +2,15 @@ [Watch the 40-minute walkthrough video on how to contribute to Next.js.](https://www.youtube.com/watch?v=cuoNzXFLitc) ---- - - Read about our [Commitment to Open Source](https://vercel.com/oss). -- To contribute to [our examples](examples), please see [Adding examples](#adding-examples) below. - Before jumping into a PR be sure to search [existing PRs](https://github.com/vercel/next.js/pulls) or [issues](https://github.com/vercel/next.js/issues) for an open or closed item that relates to your submission. ## Repository -- [Pull Request Descriptions](./contributing/repository/pull-request-descriptions.md) -- [Linting](./contributing/repository/linting.md) -- [Publishing](./contributing/repository/publishing.md) - [Triaging](./contributing/repository/triaging.md) +- [Release Channels and Publishing](./contributing/repository/release-channels-publishing.md) +- [Linting](./contributing/repository/linting.md) +- [Pull Request Descriptions](./contributing/repository/pull-request-descriptions.md) ## Core @@ -29,5 +26,7 @@ ## Examples +- To contribute to [our examples](./examples), please see [Adding examples](./contributing/examples/adding-examples.md). + - [Adding Examples](./contributing/examples/adding-examples.md) - [Run Example Apps](./contributing/examples/run-example-apps.md) diff --git a/contributing/core/developing-using-local-app.md b/contributing/core/developing-using-local-app.md index 413a6924efdd..0d1b54e814ac 100644 --- a/contributing/core/developing-using-local-app.md +++ b/contributing/core/developing-using-local-app.md @@ -1,4 +1,4 @@ -# Developing With Your Local Version of Next.js +# Developing Using Your Local Version of Next.js There are two options to develop with your local version of the codebase: diff --git a/contributing/core/developing.md b/contributing/core/developing.md index 2f589120ede8..b08d4c692eb0 100644 --- a/contributing/core/developing.md +++ b/contributing/core/developing.md @@ -1,42 +1,44 @@ # Developing -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. +- 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. To develop locally: -1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your - own GitHub account and then - [clone](https://help.github.com/articles/cloning-a-repository/) 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): - - ```sh - git clone --depth=1 https://github.com/vercel/next.js +1. Install the [GitHub CLI](TODO). +1. Clone the Next.js repository: ``` - -2. Create a new branch: + gh repo clone vercel/next.js` ``` - git checkout -b MY_BRANCH_NAME +1. Create a new branch: ``` -3. Enable pnpm: + git checkout -b MY_BRANCH_NAME origin/canary + ``` +1. Enable pnpm: ``` corepack enable pnpm ``` -4. Install the dependencies with: +1. Install the dependencies with: ``` pnpm install ``` -5. Start developing and watch for code changes: +1. Start developing and watch for code changes: ``` pnpm dev ``` -6. In a new terminal, run `pnpm types` to compile declaration files from +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 you 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 with your local version of Next.js](#developing-with-your-local-version-of-nextjs)** -below. (Naively linking the binary is not sufficient to develop locally.) +see **[Developing Using Your Local Version of Next.js](./developing-using-local-app.md)** as linking the package is not sufficient to develop locally. diff --git a/contributing/repository/publishing.md b/contributing/repository/release-channels-publishing.md similarity index 97% rename from contributing/repository/publishing.md rename to contributing/repository/release-channels-publishing.md index 73344938c47f..5286572a418d 100644 --- a/contributing/repository/publishing.md +++ b/contributing/repository/release-channels-publishing.md @@ -1,4 +1,4 @@ -# Publishing +# Release Channels and Publishing Next.js has two release channels: `stable` and `canary`. From 338f60ddc7c8d7f68ff4f8ae6965d8c254ada7d5 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 21:21:12 +0100 Subject: [PATCH 07/27] Add additional notes on running tests and simplify command to pnpm test --- contributing/core/testing.md | 26 +++++++++++++++++--------- package.json | 1 + 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/contributing/core/testing.md b/contributing/core/testing.md index 2bd6d9970d8a..a7ad4e46bb11 100644 --- a/contributing/core/testing.md +++ b/contributing/core/testing.md @@ -1,27 +1,35 @@ # Testing -See the [testing readme](./test/readme.md) for information on writing tests. +See the [testing readme](../..//test/readme.md) for information on writing tests. ### Running tests +We recommend running the tests in headless mode (with the browser windows hidden) and wih a specific directory pattern (`--testPathPattern`) or test name (`-t`) which ensure 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 testonly -``` +pnpm test --testPathPattern "test/integration/production" -t "should allow etag header support" +```` -If you would like to run the tests in headless mode (with the browser windows hidden) you can do +Running all tests in the `test/integration/production` test suite: ```sh -pnpm testheadless +pnpm test --testPathPattern "test/integration/production" ``` -Running a specific test suite (e.g. `production`) inside of the `test/integration` directory: +Running all tests (⚠️ not recommended locally): ```sh -pnpm testonly --testPathPattern "production" +pnpm test ``` -Running one test in the `production` test suite: +When you want to debug a particular tests 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 "production" -t "should allow etag header support" +pnpm testonly --testPathPattern "test/integration/production" -t "should allow etag header support" ``` diff --git a/package.json b/package.json index fbc7d8c6f297..7e04045b02c6 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "test-dev": "cross-env NEXT_TEST_MODE=dev pnpm testheadless", "test-start": "cross-env NEXT_TEST_MODE=start pnpm testheadless", "test-deploy": "cross-env NEXT_TEST_MODE=deploy pnpm testheadless", + "test": "cross-env HEADLESS=true pnpm testonly", "testonly": "pnpm jest --runInBand", "testheadless": "cross-env HEADLESS=true pnpm testonly", "genstats": "cross-env LOCAL_STATS=true node .github/actions/next-stats-action/src/index.js", From 3346f7a4773f5927eda710dd64de46e1635538cc Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 21:23:48 +0100 Subject: [PATCH 08/27] Update explanation on build --- contributing/core/building.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/contributing/core/building.md b/contributing/core/building.md index 3970b38ff0b1..cc9950e29d75 100644 --- a/contributing/core/building.md +++ b/contributing/core/building.md @@ -1,11 +1,9 @@ # Building -You can build the project, including all type definitions, with: +You can build Next.js, including all type definitions and packages, with: ```bash 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](https://www.rust-lang.org/tools/install) and run `pnpm --filter=@next/swc build-native`. From eaee5bf7bc1ec7ee7acd5ba1703fd8d0b9fc7a0b Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Fri, 19 Aug 2022 21:26:25 +0100 Subject: [PATCH 09/27] Reword error-links --- contributing/core/adding-error-links.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/core/adding-error-links.md b/contributing/core/adding-error-links.md index 6778ca1ea9fe..394a43450778 100644 --- a/contributing/core/adding-error-links.md +++ b/contributing/core/adding-error-links.md @@ -1,8 +1,8 @@ # Adding Warning and Error Descriptions -In Next.js we have a system to add helpful links to warnings and errors. +Next.js has 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. +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. From 8be9a9c727dfb0a931d1d982d1e916b34a4085d9 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Sat, 20 Aug 2022 14:46:27 +0200 Subject: [PATCH 10/27] Comment out todo --- contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index d8fd2b4a2896..37a1f5eb618b 100644 --- a/contributing.md +++ b/contributing.md @@ -10,7 +10,7 @@ - [Triaging](./contributing/repository/triaging.md) - [Release Channels and Publishing](./contributing/repository/release-channels-publishing.md) - [Linting](./contributing/repository/linting.md) -- [Pull Request Descriptions](./contributing/repository/pull-request-descriptions.md) + ## Core From 323d2d564426c85650b44957202fa3756e432545 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Sat, 20 Aug 2022 14:46:39 +0200 Subject: [PATCH 11/27] Ask why and the fix for errors --- errors/template.txt | 4 ++++ plopfile.js | 19 +++++++++++++++++-- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/errors/template.txt b/errors/template.txt index 3aa3e131acac..5905279b8626 100644 --- a/errors/template.txt +++ b/errors/template.txt @@ -4,10 +4,14 @@ +{{why}} + #### Possible Ways to Fix It +{{fix}} + ### Useful Links diff --git a/plopfile.js b/plopfile.js index 44cbe6eec120..3d50710ea20d 100644 --- a/plopfile.js +++ b/plopfile.js @@ -50,14 +50,29 @@ module.exports = function (plop) { plop.setGenerator('error', { description: 'Create a new error document', prompts: [ + { + name: 'urlPath', + type: 'input', + message: 'Url path with dashes. E.g. circular-structure', + }, { name: 'title', type: 'input', - message: 'Title for the error', + message: 'Title for the error. E.g. Circular Structure', + }, + { + name: 'why', + type: 'input', + message: 'What caused the error to happen?', + }, + { + name: 'fix', + type: 'input', + message: 'What are the possible ways to fix it?', }, ], actions: function (data) { - const fileName = getFileName(data.title) + const fileName = getFileName(data.urlPath) return [ { type: 'add', From a5de8b50bf4202bffbf2531abb908bad4bb66f60 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Sat, 20 Aug 2022 14:53:08 +0200 Subject: [PATCH 12/27] Log the url for the error --- contributing/core/adding-error-links.md | 6 +----- plopfile.js | 1 + 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/contributing/core/adding-error-links.md b/contributing/core/adding-error-links.md index 394a43450778..0f6ccb3d6622 100644 --- a/contributing/core/adding-error-links.md +++ b/contributing/core/adding-error-links.md @@ -9,8 +9,4 @@ 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. Add the following url to your warning/error: - `https://nextjs.org/docs/messages/`. - - For example, to link to `errors/api-routes-static-export.md` you use the url: - `https://nextjs.org/docs/messages/api-routes-static-export` +2. At the end of the command the URL for the error will be provided, add that to your error. diff --git a/plopfile.js b/plopfile.js index 3d50710ea20d..e8277c7bb19f 100644 --- a/plopfile.js +++ b/plopfile.js @@ -91,6 +91,7 @@ module.exports = function (plop) { return JSON.stringify(manifestData, null, 2) }, }, + `Url for the error: https://nextjs.org/docs/messages/${fileName}`, ] }, }) From 74e857bf3e6bf40b0ed64efeefea5213ecb8a28f Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Sat, 20 Aug 2022 15:09:28 +0200 Subject: [PATCH 13/27] Add placeholder for vscode debugger --- contributing.md | 1 + contributing/core/vscode-debugger.md | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 contributing/core/vscode-debugger.md diff --git a/contributing.md b/contributing.md index 37a1f5eb618b..c1ea4cb56426 100644 --- a/contributing.md +++ b/contributing.md @@ -19,6 +19,7 @@ - [Testing](./contributing/core/testing.md) - [Adding Error Links](./contributing/core/adding-error-links.md) - [Developing Using Local App](./contributing/core/developing-using-local-app.md) + ## Documentation diff --git a/contributing/core/vscode-debugger.md b/contributing/core/vscode-debugger.md new file mode 100644 index 000000000000..d75ac174bf32 --- /dev/null +++ b/contributing/core/vscode-debugger.md @@ -0,0 +1,3 @@ +# Using the VS Code Debugger + +TODO From 89afdef57a2760aff4c8ce554212c6d36fa61a26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Tue, 13 Sep 2022 15:19:23 +0200 Subject: [PATCH 14/27] mention `pnpm next` https://github.com/vercel/next.js/pull/39778#discussion_r951270652 --- contributing/core/developing-using-local-app.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/contributing/core/developing-using-local-app.md b/contributing/core/developing-using-local-app.md index 1f91fa770533..320e00e4cdf0 100644 --- a/contributing/core/developing-using-local-app.md +++ b/contributing/core/developing-using-local-app.md @@ -4,14 +4,16 @@ 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` -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). - ## Set as a local dependency in package.json 1. In your app's `package.json`, replace: From 21a761493ad2873e32746dfa047b452c14d604b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Tue, 13 Sep 2022 15:28:00 +0200 Subject: [PATCH 15/27] `stable` -> `canary` Ref: https://github.com/vercel/next.js/pull/39778#discussion_r950906888 --- contributing/repository/release-channels-publishing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/repository/release-channels-publishing.md b/contributing/repository/release-channels-publishing.md index 5286572a418d..8eb4dce091f4 100644 --- a/contributing/repository/release-channels-publishing.md +++ b/contributing/repository/release-channels-publishing.md @@ -6,7 +6,7 @@ Next.js has two release channels: `stable` and `canary`. The stable release is what is installed when you `npm install next`. This channel is used by the majority of Next.js users. -This channel is published at a regular cadence and follows [semantic versioning](TODO). +This channel is published at a regular cadence and follows [semantic versioning](https://semver.org). Repository maintainers can publish a new stable version using: `pnpm publish-stable`. The command will ask what version to publish `major`, `minor`, or `patch`. @@ -21,5 +21,5 @@ This channel is published early based on the `canary` branch. It holds all chang By installing `next@canary` from time to time you can check if your application is affected by any changes that have not been published yet. -Repository maintainers can publish a new stable version using: `pnpm publish-stable`. +Repository maintainers can publish a new canary version using: `pnpm publish-canary`. The command will automatically decide the new version tag as it's an increment from the previous version. From 8471e2fe2bab985d69800f0387a2d3e800b8322f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Tue, 13 Sep 2022 15:30:22 +0200 Subject: [PATCH 16/27] add GitHub CLI install link --- contributing/core/developing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/core/developing.md b/contributing/core/developing.md index b08d4c692eb0..09e60062198b 100644 --- a/contributing/core/developing.md +++ b/contributing/core/developing.md @@ -6,7 +6,7 @@ To develop locally: -1. Install the [GitHub CLI](TODO). +1. Install the [GitHub CLI](https://github.com/cli/cli#installation). 1. Clone the Next.js repository: ``` gh repo clone vercel/next.js` From b12aecf1b2eb9f85c2846facaa445c5342ce58bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Tue, 13 Sep 2022 15:32:45 +0200 Subject: [PATCH 17/27] remove redundant section --- contributing.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/contributing.md b/contributing.md index ae4c86b78334..2c7c7d5506c2 100644 --- a/contributing.md +++ b/contributing.md @@ -23,10 +23,6 @@ - [Adding Examples](./contributing/examples/adding-examples.md) - [Run Example Apps](./contributing/examples/run-example-apps.md) -For instructions on how to build a project with your local version of the CLI, -see **[Developing with your local version of Next.js](#developing-with-your-local-version-of-nextjs)** -below. - ## Core - [Developing](./contributing/core/developing.md) From 87c6c0dca5e3622a357816cbdb9160e2c3c89aa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Wed, 14 Sep 2022 14:27:00 +0200 Subject: [PATCH 18/27] simplify local dependency development notes --- .../core/developing-using-local-app.md | 40 ++++--------------- 1 file changed, 7 insertions(+), 33 deletions(-) diff --git a/contributing/core/developing-using-local-app.md b/contributing/core/developing-using-local-app.md index 320e00e4cdf0..bb7a5e51c35f 100644 --- a/contributing/core/developing-using-local-app.md +++ b/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": "", - "react": "", - "react-dom": "", - ``` - - 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 From c7ab3e82c2604f6e402ae220fc469918b0ebeaaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Thu, 15 Sep 2022 13:02:42 +0200 Subject: [PATCH 19/27] tweak testing docs --- contributing/core/testing.md | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/contributing/core/testing.md b/contributing/core/testing.md index 424476dc4832..e745893fc97a 100644 --- a/contributing/core/testing.md +++ b/contributing/core/testing.md @@ -2,7 +2,7 @@ ## 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: @@ -10,43 +10,37 @@ 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. From 3a5cb132df41a8be5e111725f3a9d99237b64003 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Thu, 15 Sep 2022 13:56:26 +0200 Subject: [PATCH 20/27] add "Using the VS Code Debugger" --- contributing/core/vscode-debugger.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/contributing/core/vscode-debugger.md b/contributing/core/vscode-debugger.md index d75ac174bf32..d240b0af040b 100644 --- a/contributing/core/vscode-debugger.md +++ b/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). From 208034b25832100f5798a6d9cf1c7ef45e80b2c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Thu, 15 Sep 2022 13:56:39 +0200 Subject: [PATCH 21/27] simplify launch.json --- .vscode/launch.json | 84 ++++++++++++++------------------------------- 1 file changed, 26 insertions(+), 58 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 16184462f33f..25aebc7992bc 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -9,93 +9,61 @@ "type": "node", "request": "launch", "cwd": "${workspaceFolder}", - "runtimeExecutable": "yarn", - "runtimeArgs": ["run", "debug-react-exp", "dev", "test/e2e/app-dir/app"], - "skipFiles": ["/**"], - "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"], - "port": 9229, - "env": { - "NEXT_PRIVATE_LOCAL_WEBPACK5": "1" - } + "runtimeExecutable": "pnpm", + "runtimeArgs": ["debug-react-exp", "dev", "test/e2e/app-dir/app"], + "skipFiles": ["/**"] }, { "name": "Launch app development", "type": "node", "request": "launch", "cwd": "${workspaceFolder}", - "runtimeExecutable": "yarn", - "runtimeArgs": ["run", "debug", "dev", "bench/nested-deps"], - "skipFiles": ["/**"], - "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"], - "port": 9229, - "env": { - "NEXT_PRIVATE_LOCAL_WEBPACK5": "1" - } + "runtimeExecutable": "pnpm", + "runtimeArgs": ["debug", "dev", "examples/hello-world"], + "skipFiles": ["/**"] }, { "name": "Launch app build", "type": "node", "request": "launch", "cwd": "${workspaceFolder}", - "runtimeExecutable": "yarn", - "runtimeArgs": ["run", "debug", "build", "bench/nested-deps"], - "skipFiles": ["/**"], - "port": 9229, - "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"], - "env": { - "NEXT_PRIVATE_LOCAL_WEBPACK5": "1" - } + "runtimeExecutable": "pnpm", + "runtimeArgs": ["debug", "build", "examples/hello-world"], + "skipFiles": ["/**"] }, { - "name": "Launch app build trace jaeger", + "name": "Launch app production", "type": "node", "request": "launch", "cwd": "${workspaceFolder}", - "runtimeExecutable": "yarn", - "runtimeArgs": ["run", "clean-trace-jaeger"], - "skipFiles": ["/**"], - "port": 9229, - "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"], - "env": { - "NEXT_PRIVATE_LOCAL_WEBPACK5": "1" - } + "runtimeExecutable": "pnpm", + "runtimeArgs": ["debug", "start", "bench/nested-deps"], + "skipFiles": ["/**"] }, { - "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"], - "skipFiles": ["/**"], - "port": 9229, - "env": { - "NEXT_PRIVATE_LOCAL_WEBPACK5": "1" - } + "runtimeExecutable": "pnpm", + "runtimeArgs": ["debug", "dev", "${fileDirname}"], + "skipFiles": ["/**"] }, { + "name": "Launch app build trace jaeger", "type": "node", - "request": "attach", - "name": "Attach to existing debugger", - "port": 9229, - "skipFiles": ["/**"], - "outFiles": ["${workspaceFolder}/packages/next/dist/**/*"], - "env": { - "NEXT_PRIVATE_LOCAL_WEBPACK5": "1" - } + "request": "launch", + "cwd": "${workspaceFolder}", + "runtimeExecutable": "pnpm", + "runtimeArgs": ["clean-trace-jaeger"], + "skipFiles": ["/**"] }, { - "name": "Launch this example", "type": "node", - "request": "launch", - "cwd": "${workspaceFolder}", - "runtimeExecutable": "yarn", - "runtimeArgs": ["run", "debug", "dev", "${fileDirname}"], - "skipFiles": ["/**"], + "request": "attach", + "name": "Attach to existing debugger", "port": 9229, - "env": { - "NEXT_PRIVATE_LOCAL_WEBPACK5": "1" - } + "skipFiles": ["/**"] } ] } From af44a54139dad389be4d82c7a34d1a30a2a2e651 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Thu, 15 Sep 2022 14:25:03 +0200 Subject: [PATCH 22/27] add back env to `launch.json` --- .vscode/launch.json | 37 ++++++++++++++++++++++++++-------- bench/nested-deps/package.json | 8 ++++---- 2 files changed, 33 insertions(+), 12 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 25aebc7992bc..a572fd7c5999 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -11,7 +11,10 @@ "cwd": "${workspaceFolder}", "runtimeExecutable": "pnpm", "runtimeArgs": ["debug-react-exp", "dev", "test/e2e/app-dir/app"], - "skipFiles": ["/**"] + "skipFiles": ["/**"], + "env": { + "NEXT_PRIVATE_LOCAL_webpack": "1" + } }, { "name": "Launch app development", @@ -20,7 +23,10 @@ "cwd": "${workspaceFolder}", "runtimeExecutable": "pnpm", "runtimeArgs": ["debug", "dev", "examples/hello-world"], - "skipFiles": ["/**"] + "skipFiles": ["/**"], + "env": { + "NEXT_PRIVATE_LOCAL_webpack": "1" + } }, { "name": "Launch app build", @@ -29,7 +35,10 @@ "cwd": "${workspaceFolder}", "runtimeExecutable": "pnpm", "runtimeArgs": ["debug", "build", "examples/hello-world"], - "skipFiles": ["/**"] + "skipFiles": ["/**"], + "env": { + "NEXT_PRIVATE_LOCAL_webpack": "1" + } }, { "name": "Launch app production", @@ -37,8 +46,11 @@ "request": "launch", "cwd": "${workspaceFolder}", "runtimeExecutable": "pnpm", - "runtimeArgs": ["debug", "start", "bench/nested-deps"], - "skipFiles": ["/**"] + "runtimeArgs": ["debug", "start", "examples/hello-world"], + "skipFiles": ["/**"], + "env": { + "NEXT_PRIVATE_LOCAL_webpack": "1" + } }, { "name": "Launch current directory in development", @@ -47,7 +59,10 @@ "cwd": "${workspaceFolder}", "runtimeExecutable": "pnpm", "runtimeArgs": ["debug", "dev", "${fileDirname}"], - "skipFiles": ["/**"] + "skipFiles": ["/**"], + "env": { + "NEXT_PRIVATE_LOCAL_webpack": "1" + } }, { "name": "Launch app build trace jaeger", @@ -56,14 +71,20 @@ "cwd": "${workspaceFolder}", "runtimeExecutable": "pnpm", "runtimeArgs": ["clean-trace-jaeger"], - "skipFiles": ["/**"] + "skipFiles": ["/**"], + "env": { + "NEXT_PRIVATE_LOCAL_webpack": "1" + } }, { "type": "node", "request": "attach", "name": "Attach to existing debugger", "port": 9229, - "skipFiles": ["/**"] + "skipFiles": ["/**"], + "env": { + "NEXT_PRIVATE_LOCAL_webpack": "1" + } } ] } diff --git a/bench/nested-deps/package.json b/bench/nested-deps/package.json index e1be9e25267f..4bef74070dac 100644 --- a/bench/nested-deps/package.json +++ b/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": { From f5b5348d6b7552af7a09c4ff2322fc0fe536039e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Fri, 16 Sep 2022 14:09:19 +0200 Subject: [PATCH 23/27] Update contributing.md --- contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index 2c7c7d5506c2..32733ca5e400 100644 --- a/contributing.md +++ b/contributing.md @@ -18,7 +18,7 @@ ## Examples -- To contribute to [our examples](./examples), please see [Adding examples](./contributing/examples/adding-examples.md). +To contribute to [our examples](./examples), please see - [Adding Examples](./contributing/examples/adding-examples.md) - [Run Example Apps](./contributing/examples/run-example-apps.md) From 50770099cbb4bf847e2ccd8be059339e25910835 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Fri, 16 Sep 2022 15:00:44 +0200 Subject: [PATCH 24/27] Update testing.md --- contributing/core/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/core/testing.md b/contributing/core/testing.md index e745893fc97a..af6678e9172b 100644 --- a/contributing/core/testing.md +++ b/contributing/core/testing.md @@ -53,7 +53,7 @@ If a test suite already exists that relates closely to the item being tested (e. ### 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 testheadless` command. +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 next` while inside of 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 of the Next.js repo instead of the temp directory, this can also reduce test times locally but is not compatible with all tests. From 47befbe6d6e599bab5a35dfcf33331512444e24e Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Fri, 16 Sep 2022 14:25:14 -0700 Subject: [PATCH 25/27] fix LOCAL_WEBPACK casing --- .vscode/launch.json | 14 +++++++------- bench/nested-deps/package.json | 8 ++++---- packages/next/bundles/webpack/packages/webpack.js | 2 +- packages/next/compiled/webpack/webpack.js | 2 +- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index a572fd7c5999..e88773d91c2c 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -13,7 +13,7 @@ "runtimeArgs": ["debug-react-exp", "dev", "test/e2e/app-dir/app"], "skipFiles": ["/**"], "env": { - "NEXT_PRIVATE_LOCAL_webpack": "1" + "NEXT_PRIVATE_LOCAL_WEBPACK": "1" } }, { @@ -25,7 +25,7 @@ "runtimeArgs": ["debug", "dev", "examples/hello-world"], "skipFiles": ["/**"], "env": { - "NEXT_PRIVATE_LOCAL_webpack": "1" + "NEXT_PRIVATE_LOCAL_WEBPACK": "1" } }, { @@ -37,7 +37,7 @@ "runtimeArgs": ["debug", "build", "examples/hello-world"], "skipFiles": ["/**"], "env": { - "NEXT_PRIVATE_LOCAL_webpack": "1" + "NEXT_PRIVATE_LOCAL_WEBPACK": "1" } }, { @@ -49,7 +49,7 @@ "runtimeArgs": ["debug", "start", "examples/hello-world"], "skipFiles": ["/**"], "env": { - "NEXT_PRIVATE_LOCAL_webpack": "1" + "NEXT_PRIVATE_LOCAL_WEBPACK": "1" } }, { @@ -61,7 +61,7 @@ "runtimeArgs": ["debug", "dev", "${fileDirname}"], "skipFiles": ["/**"], "env": { - "NEXT_PRIVATE_LOCAL_webpack": "1" + "NEXT_PRIVATE_LOCAL_WEBPACK": "1" } }, { @@ -73,7 +73,7 @@ "runtimeArgs": ["clean-trace-jaeger"], "skipFiles": ["/**"], "env": { - "NEXT_PRIVATE_LOCAL_webpack": "1" + "NEXT_PRIVATE_LOCAL_WEBPACK": "1" } }, { @@ -83,7 +83,7 @@ "port": 9229, "skipFiles": ["/**"], "env": { - "NEXT_PRIVATE_LOCAL_webpack": "1" + "NEXT_PRIVATE_LOCAL_WEBPACK": "1" } } ] diff --git a/bench/nested-deps/package.json b/bench/nested-deps/package.json index 4bef74070dac..91c3fca60c60 100644 --- a/bench/nested-deps/package.json +++ b/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_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": "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_webpack=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": { diff --git a/packages/next/bundles/webpack/packages/webpack.js b/packages/next/bundles/webpack/packages/webpack.js index e4eccb4b126a..11c019e0d676 100644 --- a/packages/next/bundles/webpack/packages/webpack.js +++ b/packages/next/bundles/webpack/packages/webpack.js @@ -3,7 +3,7 @@ exports.__esModule = true exports.default = undefined exports.init = function () { - if (process.env.NEXT_PRIVATE_LOCAL_webpack) { + if (process.env.NEXT_PRIVATE_LOCAL_WEBPACK) { Object.assign(exports, { // eslint-disable-next-line import/no-extraneous-dependencies BasicEvaluatedExpression: require('webpack/lib/javascript/BasicEvaluatedExpression'), diff --git a/packages/next/compiled/webpack/webpack.js b/packages/next/compiled/webpack/webpack.js index e4eccb4b126a..11c019e0d676 100644 --- a/packages/next/compiled/webpack/webpack.js +++ b/packages/next/compiled/webpack/webpack.js @@ -3,7 +3,7 @@ exports.__esModule = true exports.default = undefined exports.init = function () { - if (process.env.NEXT_PRIVATE_LOCAL_webpack) { + if (process.env.NEXT_PRIVATE_LOCAL_WEBPACK) { Object.assign(exports, { // eslint-disable-next-line import/no-extraneous-dependencies BasicEvaluatedExpression: require('webpack/lib/javascript/BasicEvaluatedExpression'), From c78a1a7659d778458a529d8affa01ac3fee9fdb7 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Fri, 16 Sep 2022 14:26:03 -0700 Subject: [PATCH 26/27] add contributing to docs change --- scripts/run-for-change.js | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/run-for-change.js b/scripts/run-for-change.js index 7b7475c802f0..846a20c98440 100644 --- a/scripts/run-for-change.js +++ b/scripts/run-for-change.js @@ -11,6 +11,7 @@ const CHANGE_ITEM_GROUPS = { 'examples', 'UPGRADING.md', 'contributing.md', + 'contributing', 'CODE_OF_CONDUCT.md', 'readme.md', ], From ffd5395afd4c029fed2c220ab316f35db3bf35d7 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Fri, 16 Sep 2022 14:36:50 -0700 Subject: [PATCH 27/27] fix formatting --- contributing/core/testing.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/contributing/core/testing.md b/contributing/core/testing.md index af6678e9172b..5f197ef5177b 100644 --- a/contributing/core/testing.md +++ b/contributing/core/testing.md @@ -6,24 +6,23 @@ We recommend running the tests in headless mode (with the browser windows hidden For example, running one test in the production test suite: -```` Running one test in the `test/integration/production` test suite: ```sh -pnpm test -- test/integration/production -t "should allow etag header support" -```` +pnpm testheadless test/integration/production/ -t "should allow etag header support" +``` Running all tests in the `test/integration/production` test suite: ```sh -pnpm test test/integration/production +pnpm testheadless 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 you want to debug a particular test you can replace `pnpm testheadless` 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 -- 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