diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1ecd7a971..00fd94cb12 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,13 +10,10 @@ Before working on an issue, ask to be assigned to it. This makes it clear to oth contributors that someone is working on the issue. When creating a PR, please use the template. The information in the template helps maintainers -review your pull request.``` +review your pull request. This project was made with ❤️. The simplest way to give back is by starring and sharing it online. -Everyone is welcome regardless of personal background. We enforce a -[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and inclusive environment. - ## Development process First fork and clone the repository. If you're not sure how to do this, please watch @@ -34,6 +31,108 @@ Make sure everything is correctly setup with: npm test ``` +## Lambda Folder structure: + +For a simple next.js app + +``` +/___netlify-server-handler +├── .netlify +│ ├── tags-manifest.json +│ └── dist // the compiled runtime code +│ └── run +│ ├── handlers +│ │ ├── server.js +│ │ └── cache.cjs +│ └── next.cjs +├── .next // or distDir name from the next.config.js +│ └── // content from standalone +├── run-config.json // the config object from the required-server-files.json +├── node_modules +├── ___netlify-server-handler.json +├── ___netlify-server-handler.mjs +└── package.json +``` + +## Testing + +The repo includes three types of tests: e2e tests in the repo that use Playwright, integration and +unit tests that use Vitest. + +By default the e2e, integration and unit tests run against the latest version of Next.js. To run +tests against a specific version, set the `NEXT_VERSION` environment variable to the desired +version. + +By default, PRs will run the tests against the latest version of Next.js. To run tests against +`latest`, `canary` and `13.5.1`, apply the `test all versions` label to the PR when you create it. +These also run nightly and on release PRs. + +### Integration testing + +> **Prerequisite** Run `npm run build` before running integration tests. + +How to add new integration test scenarios to the application: + +1. Create a new folder under `tests/fixtures/` +2. Adapt the `next.config.js` to be a standalone application +3. Create a `postinstall` script that runs the `next build`. It's important to notice that the + integration tests rely on a already built next.js application in this folder. They rely on the + `.next` folder. +4. Add your test + +> Currently the tests require a built version of the `dist/run/handlers/cache.cjs` so you need to +> run `npm run build` before executing the integration tests. + +In addition, the integration tests need to be prepared before first use. You can do this by running +`npm run pretest`. To speed up this process and build only the fixtures whose name starts with a +given prefix, run `npm run pretest -- `. + +### E2E testing + +> **Prerequisite** +> +> Needs the `netlify-cli` installed and being logged in having access to Netlify Testing +> Organization or providing your own site ID with NETLIFY_SITE_ID environment variable. + +The e2e tests can be invoked with `npm run e2e` and perform a full e2e test. This means they do the +following: + +1. Building the next-runtime (just running `npm run build` in the repository) +2. Creating a temp directory and copying the provided fixture over to the directory. +3. Packing the runtime with `npm pack` to the temp directory. +4. Installing the runtime from the created zip artifact of `npm pack` (this is like installing a + node_module from the registry) +5. Creating a `netlify.toml` inside the temp directory of the fixture and adding the runtime as a + plugin. +6. Running `netlify deploy --build` invoking the runtime. This will use the + [next-runtime-testing](https://app.netlify.com/sites/next-runtime-testing/overview) as site to + deploy to. +7. Using the `deployId` and `url` of the deployed site to run some + [playwright](https://playwright.dev/) tests against, asserting the correctness of the runtime. +8. After the tests where run successfully, it will delete the deployment again and clean everything + up. In case of a failure, the deploy won't be cleaned up to leave it for troubleshooting + purposes. + +> [!TIP] If you'd like to always keep the deployment and the local fixture around for +> troubleshooting, run `E2E_PERSIST=1 npm run e2e`. + +### Next.js tests + +There is a script `run-local-test.sh` and GitHub workflow that runs the e2e tests from the Next.js +repo against this repo. It requires that `next.js` is checked out in the same parent directory as +this repo, and is run from this repo with `./run-local-test.sh your-test-pattern-here`. + +#### cleanup old deploys + +To cleanup old and dangling deploys from failed builds you can run the following script: + +```bash +npx tsx ./tools/e2e/cleanup-deploys.ts +``` + +This will cleanup all created deploys on the +[next-runtime-testing](https://app.netlify.com/sites/next-runtime-testing/overview) site. + ## How to write commit messages We use [Conventional Commit messages](https://www.conventionalcommits.org/) to automate version @@ -45,11 +144,6 @@ Most common commit message prefixes are: - `feat:` which represents a new feature, and generate a minor release. - `feat!:`, `fix!:` or `refactor!:` and generate a major release. -## Releasing - -This repository uses [release-please](https://github.com/googleapis/release-please) to automate its -releases. - ## How to make a minimal reproduction A reproducible test case is a small Next.js site built to demonstrate a problem - often this problem diff --git a/README.md b/README.md index 4138be43a4..36c7cebd96 100644 --- a/README.md +++ b/README.md @@ -1,105 +1,18 @@ -# Next.js Runtime - -Next.js is supported natively on Netlify, and in most cases you will not need to install or -configure anything. This repo includes the packages used to support Next.js on Netlify. - -## Lambda Folder structure: - -For a simple next.js app - -``` -/___netlify-server-handler -├── .netlify -│ ├── tags-manifest.json -│ └── dist // the compiled runtime code -│ └── run -│ ├── handlers -│ │ ├── server.js -│ │ └── cache.cjs -│ └── next.cjs -├── .next // or distDir name from the next.config.js -│ └── // content from standalone -├── run-config.json // the config object from the required-server-files.json -├── node_modules -├── ___netlify-server-handler.json -├── ___netlify-server-handler.mjs -└── package.json -``` - -## Testing - -The repo includes two types of tests: e2e tests in the repo that use Playwright, integration tests -that use Vitest. - -By default the e2e and integration tests run against the latest version of Next.js. To run tests -against a specific version, set the `NEXT_VERSION` environment variable to the desired version. - -By default, PRs will run the integration tests against the latest version of Next.js. To run tests -against `latest`, `canary` and `13.5.1`, apply the `test all versions` label to the PR when you -create it. These also run nightly and on release PRs. - -### Integration testing - -> **Prerequisite** Run `npm run build` before running integration tests. - -How to add new integration test scenarios to the application: - -1. Create a new folder under `tests/fixtures/` -2. Adapt the `next.config.js` to be a standalone application -3. Create a `postinstall` script that runs the `next build`. It's important to notice that the - integration tests rely on a already built next.js application in this folder. They rely on the - `.next` folder. -4. Add your test - -> Currently the tests require a built version of the `dist/run/handlers/cache.cjs` so you need to -> run `npm run build` before executing the integration tests. - -In addition, the integration tests need to be prepared before first use. You can do this by running -`npm run pretest`. To speed up this process and build only the fixtures whose name starts with a -given prefix, run `npm run pretest -- `. - -### E2E testing - -> **Prerequisite** -> -> Needs the `netlify-cli` installed and being logged in having access to Netlify Testing -> Organization - -The e2e tests can be invoked with `npm run e2e` and perform a full e2e test. This means they do the -following: - -1. Building the next-runtime (just running `npm run build` in the repository) -2. Creating a temp directory and copying the provided fixture over to the directory. -3. Packing the runtime with `npm pack` to the temp directory. -4. Installing the runtime from the created zip artifact of `npm pack` (this is like installing a - node_module from the registry) -5. Creating a `netlify.toml` inside the temp directory of the fixture and adding the runtime as a - plugin. -6. Running `netlify deploy --build` invoking the runtime. This will use the - [next-runtime-testing](https://app.netlify.com/sites/next-runtime-testing/overview) as site to - deploy to. -7. Using the `deployId` and `url` of the deployed site to run some - [playwright](https://playwright.dev/) tests against, asserting the correctness of the runtime. -8. After the tests where run successfully, it will delete the deployment again and clean everything - up. In case of a failure, the deploy won't be cleaned up to leave it for troubleshooting - purposes. - -> [!TIP] If you'd like to always keep the deployment and the local fixture around for -> troubleshooting, run `E2E_PERSIST=1 npm run e2e`. - -### Next.js tests - -There is a script `run-local-test.sh` and GitHub workflow that runs the e2e tests from the Next.js -repo against this repo. It requires that `next.js` is checked out in the same parent directory as -this repo, and is run from this repo with `./run-local-test.sh your-test-pattern-here`. - -#### cleanup old deploys - -To cleanup old and dangling deploys from failed builds you can run the following script: - -```bash -npx tsx ./tools/e2e/cleanup-deploys.ts -``` - -This will cleanup all created deploys on the -[next-runtime-testing](https://app.netlify.com/sites/next-runtime-testing/overview) site. +![Next.js Runtime](https://github.com/netlify/next-runtime/raw/main/next-js-runtime.png) + +# `@netlify/plugin-nextjs` + +

+ + + + + + +

+ +This package handles the build process and creates the runtime environment for Next.js sites on +Netlify. You should not normally need to install it yourself, as it is used automatically during +builds of Next.js sites. See +[the docs for using Next.js on Netlify](https://docs.netlify.com/frameworks/next-js/overview/) for +more details. diff --git a/next-js-runtime.png b/next-js-runtime.png new file mode 100644 index 0000000000..09f8c1f2b9 Binary files /dev/null and b/next-js-runtime.png differ