From 567e54fe3fb344a29751bf8b1d38fb2157546035 Mon Sep 17 00:00:00 2001 From: Heb Date: Mon, 17 Mar 2025 19:38:15 +0700 Subject: [PATCH 01/12] docs: add cloudflare workers section Cloudflare Workers is going to be in the future the main way to deploy application on Cloudflare, presenting it first makes sense. This also includes some re-organizing of the cloudflare pages section. --- content/3.deploy/cloudflare.md | 83 +++++++++++++++++++++++++++++----- 1 file changed, 71 insertions(+), 12 deletions(-) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index fbfd27356..919bd7d7d 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -7,29 +7,68 @@ nitroPreset: 'cloudflare' website: 'https://pages.cloudflare.com/' --- -## Cloudflare Pages +## Cloudflare Workers -::tip -**Zero Configuration ✨** -:br -Integration with Cloudflare Pages is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers). -:: +Cloudflare Workers supports [static assets](https://developers.cloudflare.com/workers/static-assets/), making it easy to deploy a Nuxt application. You can learn more about it on the [Cloudflare documentation](https://developers.cloudflare.com/workers/frameworks/framework-guides/nuxt/). + +::note +You must set a compatibility date to `2024-09-19` or later in both `nuxt.config.ts` and `wrangler.toml`. +Checkout the [Nitro documentation](https://nitro.build/deploy/providers/cloudflare#cloudflare-module-workers) for the `cloudflare_module` preset. +:: ::important -Checkout the [@nuxthub/core](/modules/hub) module to build full-stack Nuxt applications with Cloudflare, learn more on [hub.nuxt.com](https://hub.nuxt.com). +Cloudflare Static Assets is in Beta. :: -### Git Integration +### Deploy With Wrangler -If you use the GitHub/GitLab integration with Cloudflare Pages, **no configuration is required**. Pushing to your repository will automatically build your project and deploy it. +You can use [wrangler](https://github.com/cloudflare/workers-sdk) to deploy your project to Cloudflare. + +1. Create a `wangler.jsonc` + +```json [wrangler.jsonc] +{ + "$schema": "https://unpkg.com/wrangler@latest/config-schema.json", + "compatibility_date": "2025-01-16", + "main": "./.output/server/index.mjs", + "assets": { + "directory": "./.output/public/", + "binding": "ASSETS" + } +} +``` + +2. Build your project for Cloudflare Workers: + + ```bash [Terminal] + npx nuxi build --preset=cloudflare_module + ``` + +3. Deploy, it will ask you to create a project for the first time: + + ```bash [Terminal] + wrangler deploy + ``` + +### Automatic Deploy With Git + +If you're using GitHub or GitLab, Cloudflare workers has an integration to automatically deploy your project. ::note -Nuxt will detect the environment to set the correct [Server/Nitro preset](https://nitro.unjs.io/deploy/providers/cloudflare). +Checkout the [Workers Build](https://developers.cloudflare.com/workers/ci-cd/builds/git-integration/) documentation for the Git Integration. :: -To leverage server-side rendering on the edge, set the build command to: `nuxt build` +::important +[Workers Build](https://developers.cloudflare.com/workers/ci-cd/builds/) is in Beta. +:: -To statically generate your website, set the build command to: `nuxt generate` +## Cloudflare Pages + +::tip +**Zero Configuration ✨** +:br +Integration with Cloudflare Pages is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers). +:: ### Route matching @@ -47,6 +86,18 @@ export default defineNuxtConfig({ }) ``` +### Git Integration + +If you use the GitHub/GitLab integration with Cloudflare Pages, **no configuration is required**. Pushing to your repository will automatically build your project and deploy it. + +::note +Nuxt will detect the environment to set the correct [Server/Nitro preset](https://nitro.unjs.io/deploy/providers/cloudflare). +:: + +To leverage server-side rendering on the edge, set the build command to: `nuxt build` + +To statically generate your website, set the build command to: `nuxt generate` + ### Direct Upload Alternatively, you can use [wrangler](https://github.com/cloudflare/workers-sdk) to upload your project to Cloudflare. @@ -67,10 +118,18 @@ In this case, you will have to set the preset manually. ## Learn more +::important +Checkout the [@nuxthub/core](/modules/hub) module to build full-stack Nuxt applications with Cloudflare, learn more on [hub.nuxt.com](https://hub.nuxt.com). +:: + ::read-more{to="https://nitro.unjs.io/deploy/providers/cloudflare" target="_blank"} Head over **Nitro documentation** to learn more about the Cloudflare deployment preset. :: +::read-more{to="https://developers.cloudflare.com/workers/static-assets/compatibility-matrix/" target="_blank"} +To chose between Workers and Pages, look at the compatibility matrix. In the future Workers will be the preferred way to deploy application on cloudflare. +:: + ::read-more{to="https://developers.cloudflare.com/pages/framework-guides/deploy-a-nuxt-site/#use-bindings-in-your-nuxt-application" target="_blank"} Head over **CloudFlare Pages** documentation to learn more about it. :: From 4c00bc3cb021746017eb4dfdb55ff72b9f8675bb Mon Sep 17 00:00:00 2001 From: Heb Date: Tue, 18 Mar 2025 00:38:17 +0700 Subject: [PATCH 02/12] chore: add "compatibility_flags": ["nodejs_compat"] --- content/3.deploy/cloudflare.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index 919bd7d7d..f409e693a 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -30,6 +30,7 @@ You can use [wrangler](https://github.com/cloudflare/workers-sdk) to deploy your { "$schema": "https://unpkg.com/wrangler@latest/config-schema.json", "compatibility_date": "2025-01-16", + "compatibility_flags": ["nodejs_compat"], // Optional "main": "./.output/server/index.mjs", "assets": { "directory": "./.output/public/", From f6ec734925d822057aed9c889a629d8b725b2871 Mon Sep 17 00:00:00 2001 From: Heb Date: Tue, 18 Mar 2025 02:52:28 +0700 Subject: [PATCH 03/12] Update content/3.deploy/cloudflare.md Co-authored-by: Pooya Parsa --- content/3.deploy/cloudflare.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index f409e693a..e1ef6839b 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -30,7 +30,7 @@ You can use [wrangler](https://github.com/cloudflare/workers-sdk) to deploy your { "$schema": "https://unpkg.com/wrangler@latest/config-schema.json", "compatibility_date": "2025-01-16", - "compatibility_flags": ["nodejs_compat"], // Optional + "compatibility_flags": ["nodejs_compat"], "main": "./.output/server/index.mjs", "assets": { "directory": "./.output/public/", From 250bc9312df2c87f7ff3773b37169b6aa9166c6f Mon Sep 17 00:00:00 2001 From: Heb Date: Tue, 18 Mar 2025 02:54:23 +0700 Subject: [PATCH 04/12] tab From b45115f2adc30666c23259986db8d84d114ea63f Mon Sep 17 00:00:00 2001 From: Heb Date: Thu, 20 Mar 2025 06:52:50 +0700 Subject: [PATCH 05/12] docs: recommend nodeCompat and deployConfig --- content/3.deploy/cloudflare.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index e1ef6839b..6556c5c89 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -24,12 +24,22 @@ Cloudflare Static Assets is in Beta. You can use [wrangler](https://github.com/cloudflare/workers-sdk) to deploy your project to Cloudflare. -1. Create a `wangler.jsonc` +1. Configure Nitro in `nuxt.config.ts` with the following configuration : + +```ts +export default defineNuxtConfig({ + compatibilityDate: "2025-03-01", + nitro: { cloudflare: { nodeCompat: true, deployConfig: true } } +}); +``` + +This approach is recommend as it will generate a properly configured minimal `wangler.jsonc` for you. If you need to add Cloudflare settings, provide your own `wrangler.jsonc` and it will be merged with the correct Nitro options. +For advanced use cases, if you want manual control over the cloudflare settings, set `nodeCompat` and `deployConfig` to false and manually provide your own `wrangler.jsonc` with the appropriate configuration : ```json [wrangler.jsonc] { "$schema": "https://unpkg.com/wrangler@latest/config-schema.json", - "compatibility_date": "2025-01-16", + "compatibility_date": "2025-01-16", "compatibility_flags": ["nodejs_compat"], "main": "./.output/server/index.mjs", "assets": { From 98e268bdb8ea1c213cb2e03dfaffe6cfdda9c15c Mon Sep 17 00:00:00 2001 From: Heb Date: Thu, 27 Mar 2025 19:30:00 +0700 Subject: [PATCH 06/12] Update content/3.deploy/cloudflare.md Co-authored-by: emily-shen <69125074+emily-shen@users.noreply.github.com> --- content/3.deploy/cloudflare.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index 6556c5c89..e665527e2 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -22,7 +22,7 @@ Cloudflare Static Assets is in Beta. ### Deploy With Wrangler -You can use [wrangler](https://github.com/cloudflare/workers-sdk) to deploy your project to Cloudflare. +You can use [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) to deploy your project to Cloudflare. 1. Configure Nitro in `nuxt.config.ts` with the following configuration : From 1fcb7fcd2f7bbe141935beb2d482bf31e75d83d5 Mon Sep 17 00:00:00 2001 From: Heb Date: Thu, 27 Mar 2025 19:30:42 +0700 Subject: [PATCH 07/12] Update content/3.deploy/cloudflare.md Co-authored-by: emily-shen <69125074+emily-shen@users.noreply.github.com> --- content/3.deploy/cloudflare.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index e665527e2..2571a44cf 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -55,7 +55,7 @@ For advanced use cases, if you want manual control over the cloudflare settings, npx nuxi build --preset=cloudflare_module ``` -3. Deploy, it will ask you to create a project for the first time: +3. Deploy with Wrangler: ```bash [Terminal] wrangler deploy From be6fd717dc4c933c5e71f4a861ca501ad763c537 Mon Sep 17 00:00:00 2001 From: Heb Date: Thu, 27 Mar 2025 19:38:33 +0700 Subject: [PATCH 08/12] Update cloudflare.md --- content/3.deploy/cloudflare.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index 2571a44cf..cd31e0005 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -9,6 +9,12 @@ website: 'https://pages.cloudflare.com/' ## Cloudflare Workers +::tip +**Zero Configuration ✨** +:br +Integration with Cloudflare Pages is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers). +:: + Cloudflare Workers supports [static assets](https://developers.cloudflare.com/workers/static-assets/), making it easy to deploy a Nuxt application. You can learn more about it on the [Cloudflare documentation](https://developers.cloudflare.com/workers/frameworks/framework-guides/nuxt/). ::note @@ -33,19 +39,20 @@ export default defineNuxtConfig({ }); ``` -This approach is recommend as it will generate a properly configured minimal `wangler.jsonc` for you. If you need to add Cloudflare settings, provide your own `wrangler.jsonc` and it will be merged with the correct Nitro options. -For advanced use cases, if you want manual control over the cloudflare settings, set `nodeCompat` and `deployConfig` to false and manually provide your own `wrangler.jsonc` with the appropriate configuration : +By setting `deployConfig: true`, Nitro will automatically generate a `wrangler.json` that points to the correct build outputs. +If you need to add [Cloudflare Workers configuration](https://developers.cloudflare.com/workers/wrangler/configuration/), such as bindings, you can either: + +- Set these in your Nuxt config under the `cloudflare: {wrangler : ... }` key. This has the same type as `wrangler.json`. +- Provide your own `wrangler.jsonc`. Nitro will automatically set the `main` and `assets.directory` keys to the correct build output. ```json [wrangler.jsonc] { "$schema": "https://unpkg.com/wrangler@latest/config-schema.json", - "compatibility_date": "2025-01-16", - "compatibility_flags": ["nodejs_compat"], - "main": "./.output/server/index.mjs", - "assets": { - "directory": "./.output/public/", - "binding": "ASSETS" - } + // Add your workers configuration here. + "observability": { + "enabled": true, + "head_sampling_rate": 0.1 + } } ``` From 17245064196ffdd29c573b19f54181a3a045310c Mon Sep 17 00:00:00 2001 From: Heb Date: Thu, 27 Mar 2025 19:39:22 +0700 Subject: [PATCH 09/12] Update content/3.deploy/cloudflare.md Co-authored-by: emily-shen <69125074+emily-shen@users.noreply.github.com> --- content/3.deploy/cloudflare.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index cd31e0005..51e30cd76 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -18,7 +18,7 @@ Integration with Cloudflare Pages is possible with zero configuration, [learn mo Cloudflare Workers supports [static assets](https://developers.cloudflare.com/workers/static-assets/), making it easy to deploy a Nuxt application. You can learn more about it on the [Cloudflare documentation](https://developers.cloudflare.com/workers/frameworks/framework-guides/nuxt/). ::note -You must set a compatibility date to `2024-09-19` or later in both `nuxt.config.ts` and `wrangler.toml`. +You must set a compatibility date to `2024-09-19` or later in both `nuxt.config.ts` and `wrangler.toml`/`wrangler.json`. Checkout the [Nitro documentation](https://nitro.build/deploy/providers/cloudflare#cloudflare-module-workers) for the `cloudflare_module` preset. :: From 13133e315b7695d8b8ebb7da1dc95b36061cc05b Mon Sep 17 00:00:00 2001 From: Heb Date: Thu, 27 Mar 2025 19:47:02 +0700 Subject: [PATCH 10/12] Update cloudflare.md --- content/3.deploy/cloudflare.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/3.deploy/cloudflare.md b/content/3.deploy/cloudflare.md index 51e30cd76..63b6d9bb0 100644 --- a/content/3.deploy/cloudflare.md +++ b/content/3.deploy/cloudflare.md @@ -68,6 +68,10 @@ If you need to add [Cloudflare Workers configuration](https://developers.cloudfl wrangler deploy ``` +::tip +While developing your project with `nuxi dev`, [nitro-cloudflare-dev](https://github.com/nitrojs/nitro-cloudflare-dev) will provide access to local simulators of Cloudflare bindings. It is an experimental module. +You can use it by adding `modules: ["nitro-cloudflare-dev"]` to your nuxt config. +:: ### Automatic Deploy With Git If you're using GitHub or GitLab, Cloudflare workers has an integration to automatically deploy your project. From 1513245a43a00f7be9d937d43e4ae29eec7e5a89 Mon Sep 17 00:00:00 2001 From: Hebilicious Date: Sat, 13 Sep 2025 20:46:51 +0700 Subject: [PATCH 11/12] docs: add advanced configuration section --- content/deploy/cloudflare.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/content/deploy/cloudflare.md b/content/deploy/cloudflare.md index ef5080564..24e628269 100644 --- a/content/deploy/cloudflare.md +++ b/content/deploy/cloudflare.md @@ -22,10 +22,6 @@ You must set a compatibility date to `2024-09-19` or later in both `nuxt.config. Checkout the [Nitro documentation](https://nitro.build/deploy/providers/cloudflare#cloudflare-module-workers) for the `cloudflare_module` preset. :: -::important -Cloudflare Static Assets is in Beta. -:: - ### Deploy With Wrangler You can use [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) to deploy your project to Cloudflare. @@ -42,7 +38,7 @@ export default defineNuxtConfig({ By setting `deployConfig: true`, Nitro will automatically generate a `wrangler.json` that points to the correct build outputs. If you need to add [Cloudflare Workers configuration](https://developers.cloudflare.com/workers/wrangler/configuration/), such as bindings, you can either: -- Set these in your Nuxt config under the `cloudflare: {wrangler : ... }` key. This has the same type as `wrangler.json`. +- Set these in your Nuxt config under the `cloudflare: { wrangler : ... }` key. This has the same type as `wrangler.json`. - Provide your own `wrangler.jsonc`. Nitro will automatically set the `main` and `assets.directory` keys to the correct build output. ```json [wrangler.jsonc] @@ -84,6 +80,28 @@ Checkout the [Workers Build](https://developers.cloudflare.com/workers/ci-cd/bui [Workers Build](https://developers.cloudflare.com/workers/ci-cd/builds/) is in Beta. :: + +### Advanced Configuration + +While the default configuration should work for most usecases, we provide ways to tailor the deployment to your needs. + +#### Custom Wrangler configuration + +It is recommended to provide a cloudflare option to nitro, but not strictly necessary. +You might have some advanced usecase where you want to process the Nitro output further before deploying it, or you might prefer manually manage the wrangler configuration. + +In this case, you can write your own `wrangler.jsonc` entirely. +You will have to set the `main` and `assets` keys manually, based on Nitro output and your own processing. + +::important +However, Nitro output format must be respected. It is possible that these will change in future versions, so be careful when upgrading Nitro or Nuxt. +:: + +#### Custom entry point + +In some (rare) cases, you might want to customize the worker entry point. For instance, there might be some new Cloudflare Workers features that you want to use, or you might want to deviate from the default behavior. +You can even go further and completely customize the worker entry point. Refer to Nitro documentation on [how to create a custom preset](https://nitro.build/deploy/custom-presets). + ## Cloudflare Pages ::tip From bf351553c6f7b278446419317d1b6cc067a9a7e3 Mon Sep 17 00:00:00 2001 From: Hebilicious Date: Sat, 13 Sep 2025 20:47:53 +0700 Subject: [PATCH 12/12] docs: capitalize --- content/deploy/cloudflare.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/deploy/cloudflare.md b/content/deploy/cloudflare.md index 24e628269..245151768 100644 --- a/content/deploy/cloudflare.md +++ b/content/deploy/cloudflare.md @@ -85,7 +85,7 @@ Checkout the [Workers Build](https://developers.cloudflare.com/workers/ci-cd/bui While the default configuration should work for most usecases, we provide ways to tailor the deployment to your needs. -#### Custom Wrangler configuration +#### Custom Wrangler Configuration It is recommended to provide a cloudflare option to nitro, but not strictly necessary. You might have some advanced usecase where you want to process the Nitro output further before deploying it, or you might prefer manually manage the wrangler configuration. @@ -97,7 +97,7 @@ You will have to set the `main` and `assets` keys manually, based on Nitro outpu However, Nitro output format must be respected. It is possible that these will change in future versions, so be careful when upgrading Nitro or Nuxt. :: -#### Custom entry point +#### Custom Entry Point In some (rare) cases, you might want to customize the worker entry point. For instance, there might be some new Cloudflare Workers features that you want to use, or you might want to deviate from the default behavior. You can even go further and completely customize the worker entry point. Refer to Nitro documentation on [how to create a custom preset](https://nitro.build/deploy/custom-presets).