diff --git a/docs/README.md b/docs/README.md index ddf5f037428ab..b0ffe5b82a271 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,6 +20,7 @@ New to contributing? Start here: - **[Technologies](./technologies.md)** - Overview of the tech stack and architecture decisions - **[Downloads Page](./downloads-page.md)** - How to add installation methods and package managers - **[Package Publishing](./package-publishing.md)** - Guidelines for publishing packages in our monorepo +- **[Cloudflare build and deployment](./cloudflare-build-and-deployment.md)** - Overview and useful information about the Cloudflare build and deployment ## For Collaborators diff --git a/docs/cloudflare-build-and-deployment.md b/docs/cloudflare-build-and-deployment.md new file mode 100644 index 0000000000000..61ff12fb06c3b --- /dev/null +++ b/docs/cloudflare-build-and-deployment.md @@ -0,0 +1,53 @@ +# Cloudflare Build and Deployment + +The Node.js Website can be built using the [OpenNext Cloudflare adapter](https://opennext.js.org/cloudflare). Such build generates a [Cloudflare Worker](https://www.cloudflare.com/en-gb/developer-platform/products/workers/) that can be deployed on the [Cloudflare](https://www.cloudflare.com) network. + +## Configurations + +There are two key configuration files related to Cloudflare deployments: + +### Wrangler Configuration + +This file defines the settings for the Cloudflare Worker, which serves the website. + +For more details, refer to the [Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/configuration/). + +Key configurations include: + +- `main`: Points to the worker generated by the OpenNext adapter. +- `account_id`: Specifies the Cloudflare account ID. This is not required for local previews but is necessary for deployments. You can obtain an account ID for free by signing up at [dash.cloudflare.com](https://dash.cloudflare.com/login). + - This is currently set to `fb4a2d0f103c6ff38854ac69eb709272`, which is the ID of a Cloudflare account controlled by Node.js, and used for testing. +- `build`: Defines the build command to generate the Node.js filesystem polyfills required for the application to run on Cloudflare Workers. This uses the [`@flarelabs/wrangler-build-time-fs-assets-polyfilling`](https://github.com/flarelabs-net/wrangler-build-time-fs-assets-polyfilling) package. +- `alias`: Maps aliases for the Node.js filesystem polyfills generated during the build process. +- `kv_namespaces`: Contains a single KV binding definition for `NEXT_INC_CACHE_KV`. This is used to implement the Next.js incremental cache. + - This is currently set up to a KV in the aforementioned Cloudflare testing account. + +### OpenNext Configuration + +This is the configuration for the OpenNext Cloudflare adapter. + +For more details, refer to the [official OpenNext documentation](https://opennext.js.org/cloudflare/get-started#4-add-an-open-nextconfigts-file). + +### Skew Protection + +While Vercel offers [version skew protection](https://vercel.com/docs/skew-protection) out of the box, such mechanism is not present on the platform level in the Cloudflare network. + +Therefore, the OpenNext adapter provides its [own implementation](https://opennext.js.org/cloudflare/howtos/skew). + +The OpenNext skew protection requires the following environment variables to be set in the Wrangler configuration file: + +- `CF_WORKER_NAME` + - The name of the worker (the same as `name`) +- `CF_ACCOUNT_ID` + - The ID of the Cloudflare account (the same as `account_id`) +- `CF_PREVIEW_DOMAIN` + - The preview domain for the worker. For Node.js, this is `nodejsorg`. + +Additionally, when deploying, an extra `CF_WORKERS_SCRIPTS_API_TOKEN` environment variable needs to be set to an API token that has the `Workers Scripts:Read` permission available on the Worker's account. + +## Scripts + +Preview and deployment of the website targeting the Cloudflare network is implemented via the following two commands: + +- `pnpm cloudflare:preview` builds the website using the OpenNext Cloudflare adapter and runs the website locally in a server simulating the Cloudflare hosting (using the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)) +- `pnpm cloudflare:deploy` builds the website using the OpenNext Cloudflare adapter and deploys the website to the Cloudflare network (using the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/))