From c8305a39b2dc689c2ac9da49a9d3d600dd6c0b70 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Fri, 25 Jul 2025 11:49:09 +0100 Subject: [PATCH 1/3] chore(meta): add Cloudflare docs Add (back) some documentation regarding the Cloudflare build, including information about ids, accounts used, skew protection, etc... --- docs/README.md | 1 + docs/cloudflare-build-and-deployment.md | 49 +++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 docs/cloudflare-build-and-deployment.md 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..851fefaed721d --- /dev/null +++ b/docs/cloudflare-build-and-deployment.md @@ -0,0 +1,49 @@ +# 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 using [Cloudflare Workers](https://www.cloudflare.com/en-gb/developer-platform/products/workers/). + +## 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, named `nodejs.org`, that the nodejs team is using for testing the Cloudflare deployment. +- `build`: Defines the build command to generate 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 `nodejs.org` Cloudflare testing account. + +### OpenNext Configuration + +This is the configuration for the OpenNext Cloudflare adapter, for more details on such configuration please 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 and the Open-next adapter provides its own implementation, for more details refer to the [OpenNext official Skew protection documentation](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 (this is the same as `account_id`, and again this is set to the Cloudflare testing account used by the nodejs team) +- `CF_PREVIEW_DOMAIN` + - The preview domain for the worker, given that the preview url for the testing Cloudflare deployments is `https://nodejs-website.nodejsorg.workers.dev/` the domain here is `nodejsorg` + +Additionally upon deployments an extra `CF_WORKERS_SCRIPTS_API_TOKEN` environment variable needs to be set. This 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/)) From 3ba9a14809c464992ffda8e641e0ad11163470a3 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Fri, 25 Jul 2025 15:13:01 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Aviv Keller Signed-off-by: Dario Piotrowicz --- docs/cloudflare-build-and-deployment.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/cloudflare-build-and-deployment.md b/docs/cloudflare-build-and-deployment.md index 851fefaed721d..68fa43c23b3ca 100644 --- a/docs/cloudflare-build-and-deployment.md +++ b/docs/cloudflare-build-and-deployment.md @@ -4,7 +4,7 @@ The Node.js Website can be built using the [OpenNext Cloudflare adapter](https:/ ## Configurations -There are two key configuration files related to Cloudflare deployments. +There are two key configuration files related to Cloudflare deployments: ### Wrangler Configuration @@ -16,30 +16,34 @@ 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, named `nodejs.org`, that the nodejs team is using for testing the Cloudflare deployment. -- `build`: Defines the build command to generate 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. + - 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 `nodejs.org` Cloudflare testing account. + - 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 on such configuration please refer to the [official OpenNext documentation](https://opennext.js.org/cloudflare/get-started#4-add-an-open-nextconfigts-file). +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 and the Open-next adapter provides its own implementation, for more details refer to the [OpenNext official Skew protection documentation](https://opennext.js.org/cloudflare/howtos/skew). +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 (this is the same as `account_id`, and again this is set to the Cloudflare testing account used by the nodejs team) + - The ID of the Cloudflare account (the same as `account_id`) - `CF_PREVIEW_DOMAIN` - - The preview domain for the worker, given that the preview url for the testing Cloudflare deployments is `https://nodejs-website.nodejsorg.workers.dev/` the domain here is `nodejsorg` + - The preview domain for the worker. For Node.js, this is `nodejsorg`. -Additionally upon deployments an extra `CF_WORKERS_SCRIPTS_API_TOKEN` environment variable needs to be set. This variable needs to be set to an API token that has the `Workers Scripts:Read` permission available on the worker's account. +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 From 9000bb4ddcdd72ee27e1ccf3e00fe899e2d77378 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Fri, 25 Jul 2025 15:16:24 +0100 Subject: [PATCH 3/3] remove unnecessary information --- docs/cloudflare-build-and-deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloudflare-build-and-deployment.md b/docs/cloudflare-build-and-deployment.md index 68fa43c23b3ca..61ff12fb06c3b 100644 --- a/docs/cloudflare-build-and-deployment.md +++ b/docs/cloudflare-build-and-deployment.md @@ -1,6 +1,6 @@ # 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 using [Cloudflare Workers](https://www.cloudflare.com/en-gb/developer-platform/products/workers/). +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