-
Notifications
You must be signed in to change notification settings - Fork 87
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: initial readme cleanup (#392)
* chore: cleanup current CONTRIBUTING.md * chore: move contributing related content from README to contributing * chore: minor updates/corrections in contributing.md * chore: copy v4 runtime readme over * chore: initial go-through old README trying to remove outdated and update things that might still be relevant * chore: use v4 package README and not v4 repo README * Update README.md Co-authored-by: Rob Stanford <[email protected]> * chore: format with prettier * chore: trigger tests Release-As: 2.0.0 --------- Co-authored-by: Rob Stanford <[email protected]> Co-authored-by: pieh <[email protected]>
- Loading branch information
3 people
authored
Apr 2, 2024
1 parent
9c0490c
commit 0e262e0
Showing
3 changed files
with
121 additions
and
114 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/<your-name>` | ||
| 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 -- <prefix>`. | ||
|
|
||
| ### 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. | ||
|  | ||
|
|
||
| # `@netlify/plugin-nextjs` | ||
|
|
||
| <p align="center"> | ||
| <a aria-label="npm version" href="https://www.npmjs.com/package/@netlify/plugin-nextjs"> | ||
| <img alt="" src="https://img.shields.io/npm/v/@netlify/plugin-nextjs"> | ||
| </a> | ||
| <a aria-label="MIT License" href="https://img.shields.io/npm/l/@netlify/plugin-nextjs"> | ||
| <img alt="" src="https://img.shields.io/npm/l/@netlify/plugin-nextjs"> | ||
| </a> | ||
| </p> | ||
|
|
||
| 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. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.