chore: initial readme cleanup (#392)

pieh · orinokai · web-flow · commit 0e262e0ed47c · 2024-04-02T11:58:30.000+02:00
* 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 &lt;me@robstanford.com&gt;

* chore: format with prettier

* chore: trigger tests

Release-As: 2.0.0

---------

Co-authored-by: Rob Stanford &lt;me@robstanford.com&gt;
Co-authored-by: pieh &lt;pieh@users.noreply.github.com&gt;
diff --git 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/<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 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
@@ -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.
+![Next.js Runtime](https://github.com/netlify/next-runtime/raw/main/next-js-runtime.png)
+
+# `@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.
diff --git a/next-js-runtime.png b/next-js-runtime.png
