From 907aeca2a2bdc53cfa3ab55a37b1ad7cc3b415a1 Mon Sep 17 00:00:00 2001 From: Life Force Date: Fri, 5 Jun 2026 17:26:01 +0200 Subject: [PATCH 1/3] docs: add multi-environment deployment guide with platformProxy Adds documentation for three-way matching requirement when deploying to multiple Cloudflare environments: - CLOUDFLARE_ENV environment variable - [env.] section in wrangler.toml - platformProxy.environment in adapter config References: withastro/astro#15917, withastro/astro#16031, withastro/docs#13897 --- .../guides/integrations-guide/cloudflare.mdx | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index e663d1a1971aa..96f4a091f4407 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -662,6 +662,66 @@ Since Astro 6.0, the integration relies on the Cloudflare Vite plugin and this b To deploy to a specific Cloudflare environment, prefix your command with the `CLOUDFLARE_ENV` variable. For example, the command `CLOUDFLARE_ENV=some-env astro build && wrangler deploy` will build your Astro project and deploy it with Wrangler using the `some-env` environment. +#### Multi-environment deployments with `platformProxy` + +When deploying to multiple Cloudflare environments (e.g., production and preview), you need to configure three things that must match: + +1. **`CLOUDFLARE_ENV` environment variable** — set during build +2. **`[env.]` section in wrangler.toml** — environment-specific bindings +3. **`platformProxy.environment`** in adapter config — tells the Vite plugin which environment to use during dev/build + +Here's a complete example for a project with `production` and `development` environments: + +```js title="astro.config.mjs" +import { defineConfig } from 'astro/config'; +import cloudflare from '@astrojs/cloudflare'; + +export default defineConfig({ + adapter: cloudflare({ + platformProxy: { + // Use CLOUDFLARE_ENV to select the right [env.] section from wrangler.toml + environment: process.env.CLOUDFLARE_ENV, + }, + }), +}); +``` + +```jsonc title="wrangler.jsonc" +{ + "name": "my-astro-app", + "compatibility_date": "2024-12-18", + "compatibility_flags": ["nodejs_compat"], + "main": "@astrojs/cloudflare/entrypoints/server", + "assets": { "directory": "./dist", "binding": "ASSETS" }, + + // Default production bindings + "kv_namespaces": [ + { "binding": "SESSION", "id": "production-kv-id" } + ], + + // Development-specific bindings + [env.development] + "name": "my-astro-app-dev", + "kv_namespaces": [ + { "binding": "SESSION", "id": "development-kv-id" } + ] +} +``` + +Then build and deploy for each environment: + +```sh +# Production +CLOUDFLARE_ENV=production astro build && wrangler deploy + +# Development/preview +CLOUDFLARE_ENV=development astro build && wrangler deploy --env development +``` + +:::caution[Environment names must match] +The value of `CLOUDFLARE_ENV` must exactly match the `[env.]` section name in your wrangler config. If they don't match, the Vite plugin won't find the correct bindings during the build, and your Worker may fail to access KV namespaces, D1 databases, or other resources. +::: + Learn how to update your [Cloudflare environments](https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/) in the [Migrate from wrangler dev guide](https://developers.cloudflare.com/workers/vite-plugin/reference/migrating-from-wrangler-dev/#cloudflare-environments). [astro-integration]: /en/guides/integrations/ From 6aaacdaee373e386a9f2a012a9c7bf97bee2eceb Mon Sep 17 00:00:00 2001 From: Life Force Date: Fri, 5 Jun 2026 17:40:01 +0200 Subject: [PATCH 2/3] docs: expand multi-environment examples with correct/incorrect patterns - Add correct examples showing production and development matching - Add incorrect examples: name mismatch, missing platformProxy, deploy mismatch - Add hardcoded single-environment example - Move issue references to collapsible details section --- .../guides/integrations-guide/cloudflare.mdx | 154 ++++++++++++++---- 1 file changed, 124 insertions(+), 30 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 96f4a091f4407..4b5c38fe42d0e 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -670,58 +670,152 @@ When deploying to multiple Cloudflare environments (e.g., production and preview 2. **`[env.]` section in wrangler.toml** — environment-specific bindings 3. **`platformProxy.environment`** in adapter config — tells the Vite plugin which environment to use during dev/build -Here's a complete example for a project with `production` and `development` environments: +##### Correct: all three match -```js title="astro.config.mjs" -import { defineConfig } from 'astro/config'; -import cloudflare from '@astrojs/cloudflare'; +**`CLOUDFLARE_ENV=production`** — everything uses `production`: -export default defineConfig({ - adapter: cloudflare({ - platformProxy: { - // Use CLOUDFLARE_ENV to select the right [env.] section from wrangler.toml - environment: process.env.CLOUDFLARE_ENV, - }, - }), -}); +```js title="astro.config.mjs" +adapter: cloudflare({ + platformProxy: { + environment: process.env.CLOUDFLARE_ENV, // "production" + }, +}), ``` ```jsonc title="wrangler.jsonc" { - "name": "my-astro-app", - "compatibility_date": "2024-12-18", - "compatibility_flags": ["nodejs_compat"], - "main": "@astrojs/cloudflare/entrypoints/server", - "assets": { "directory": "./dist", "binding": "ASSETS" }, - - // Default production bindings + "name": "my-app", "kv_namespaces": [ - { "binding": "SESSION", "id": "production-kv-id" } + { "binding": "SESSION", "id": "prod-kv-abc123" } ], - // Development-specific bindings - [env.development] - "name": "my-astro-app-dev", - "kv_namespaces": [ - { "binding": "SESSION", "id": "development-kv-id" } - ] + "env.production": { + "name": "my-app-production", + "kv_namespaces": [ + { "binding": "SESSION", "id": "prod-kv-abc123" } + ] + }, + + "env.development": { + "name": "my-app-dev", + "kv_namespaces": [ + { "binding": "SESSION", "id": "dev-kv-xyz789" } + ] + } } ``` -Then build and deploy for each environment: +```sh +CLOUDFLARE_ENV=production astro build && wrangler deploy --env production +# ✓ platformProxy reads "production" +# ✓ wrangler.toml has "env.production" section +# ✓ wrangler deploys to "production" environment +``` + +--- + +**`CLOUDFLARE_ENV=development`** — same config, different env: ```sh -# Production -CLOUDFLARE_ENV=production astro build && wrangler deploy +CLOUDFLARE_ENV=development astro build && wrangler deploy --env development +# ✓ platformProxy reads "development" +# ✓ wrangler.toml has "env.development" section +# ✓ wrangler deploys to "development" environment +``` -# Development/preview +--- + +##### Incorrect: `CLOUDFLARE_ENV` doesn't match any `[env.*]` section + +```jsonc title="wrangler.jsonc" +{ + "env.production": { ... }, + "env.development": { ... } + // No "env.staging" section +} +``` + +```sh +CLOUDFLARE_ENV=staging astro build && wrangler deploy --env staging +# ✗ platformProxy reads "staging" — no matching section in wrangler.toml +# ✗ Vite plugin uses top-level (production) bindings instead +# ✗ Build succeeds but uses wrong KV/D1 bindings +``` + +--- + +##### Incorrect: `platformProxy` missing — Vite plugin ignores `CLOUDFLARE_ENV` + +```js title="astro.config.mjs" +adapter: cloudflare({ + // platformProxy not set +}), +``` + +```sh CLOUDFLARE_ENV=development astro build && wrangler deploy --env development +# ✗ platformProxy not configured — Vite plugin doesn't read CLOUDFLARE_ENV +# ✗ astro dev uses top-level (production) bindings +# ✗ Build may work but dev server has wrong bindings +``` + +--- + +##### Incorrect: `wrangler deploy --env` doesn't match build env + +```js title="astro.config.mjs" +adapter: cloudflare({ + platformProxy: { + environment: process.env.CLOUDFLARE_ENV, // "development" + }, +}), +``` + +```sh +CLOUDFLARE_ENV=development astro build && wrangler deploy --env production +# ✗ Build used "development" bindings (KV id: dev-kv-xyz789) +# ✗ Deploy targets "production" environment (expects prod-kv-abc123) +# ✗ Worker runs with dev bindings in production +``` + +--- + +##### Correct: hardcoded for single-environment projects + +If you only have one environment, hardcoding is fine: + +```js title="astro.config.mjs" +adapter: cloudflare({ + platformProxy: { + environment: 'production', // hardcoded + }, +}), +``` + +```sh +astro build && wrangler deploy +# ✓ Always uses production bindings +# ✓ No CLOUDFLARE_ENV needed ``` :::caution[Environment names must match] The value of `CLOUDFLARE_ENV` must exactly match the `[env.]` section name in your wrangler config. If they don't match, the Vite plugin won't find the correct bindings during the build, and your Worker may fail to access KV namespaces, D1 databases, or other resources. ::: +#### Further reading + +
+Issues and PRs that contributed to this solution + +- [PR #11445](https://github.com/withastro/docs/pull/11445) — Added `platformProxy.environment` option docs +- [PR #13578](https://github.com/withastro/docs/pull/13578) — Added `CLOUDFLARE_ENV` variable docs +- [#15917](https://github.com/withastro/astro/issues/15917) — Users documented the three-way matching workaround +- [#16031](https://github.com/withastro/astro/issues/16031) — Same issue, suggested `cloudflareEnv` adapter option +- [#14540](https://github.com/withastro/astro/issues/14540) — Independent discovery of the same workaround +- [#13897](https://github.com/withastro/docs/issues/13897) — Misleading env vars documentation + +
+ Learn how to update your [Cloudflare environments](https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/) in the [Migrate from wrangler dev guide](https://developers.cloudflare.com/workers/vite-plugin/reference/migrating-from-wrangler-dev/#cloudflare-environments). [astro-integration]: /en/guides/integrations/ From 60aef6966f3ef2f42c8395d691c03c036681dd76 Mon Sep 17 00:00:00 2001 From: Life Force Date: Fri, 5 Jun 2026 17:44:56 +0200 Subject: [PATCH 3/3] docs: simplify multi-environment section, move examples to PR description Keep docs concise with working solution. Extended examples (correct/incorrect patterns, issue references) moved to PR description for maintainers to cherry-pick. --- .../guides/integrations-guide/cloudflare.mdx | 141 +++--------------- 1 file changed, 18 insertions(+), 123 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 4b5c38fe42d0e..acd144760a55b 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -664,22 +664,23 @@ To deploy to a specific Cloudflare environment, prefix your command with the `CL #### Multi-environment deployments with `platformProxy` -When deploying to multiple Cloudflare environments (e.g., production and preview), you need to configure three things that must match: +When deploying to multiple Cloudflare environments, three things must match: -1. **`CLOUDFLARE_ENV` environment variable** — set during build -2. **`[env.]` section in wrangler.toml** — environment-specific bindings -3. **`platformProxy.environment`** in adapter config — tells the Vite plugin which environment to use during dev/build - -##### Correct: all three match - -**`CLOUDFLARE_ENV=production`** — everything uses `production`: +1. **`CLOUDFLARE_ENV`** — environment variable set during build +2. **`[env.]`** — section in wrangler.toml with environment-specific bindings +3. **`platformProxy.environment`** — adapter option that tells the Vite plugin which environment to use ```js title="astro.config.mjs" -adapter: cloudflare({ - platformProxy: { - environment: process.env.CLOUDFLARE_ENV, // "production" - }, -}), +import { defineConfig } from 'astro/config'; +import cloudflare from '@astrojs/cloudflare'; + +export default defineConfig({ + adapter: cloudflare({ + platformProxy: { + environment: process.env.CLOUDFLARE_ENV, + }, + }), +}); ``` ```jsonc title="wrangler.jsonc" @@ -689,13 +690,6 @@ adapter: cloudflare({ { "binding": "SESSION", "id": "prod-kv-abc123" } ], - "env.production": { - "name": "my-app-production", - "kv_namespaces": [ - { "binding": "SESSION", "id": "prod-kv-abc123" } - ] - }, - "env.development": { "name": "my-app-dev", "kv_namespaces": [ @@ -706,116 +700,17 @@ adapter: cloudflare({ ``` ```sh -CLOUDFLARE_ENV=production astro build && wrangler deploy --env production -# ✓ platformProxy reads "production" -# ✓ wrangler.toml has "env.production" section -# ✓ wrangler deploys to "production" environment -``` - ---- - -**`CLOUDFLARE_ENV=development`** — same config, different env: - -```sh -CLOUDFLARE_ENV=development astro build && wrangler deploy --env development -# ✓ platformProxy reads "development" -# ✓ wrangler.toml has "env.development" section -# ✓ wrangler deploys to "development" environment -``` - ---- - -##### Incorrect: `CLOUDFLARE_ENV` doesn't match any `[env.*]` section - -```jsonc title="wrangler.jsonc" -{ - "env.production": { ... }, - "env.development": { ... } - // No "env.staging" section -} -``` - -```sh -CLOUDFLARE_ENV=staging astro build && wrangler deploy --env staging -# ✗ platformProxy reads "staging" — no matching section in wrangler.toml -# ✗ Vite plugin uses top-level (production) bindings instead -# ✗ Build succeeds but uses wrong KV/D1 bindings -``` - ---- +# Production (uses top-level bindings) +CLOUDFLARE_ENV=production astro build && wrangler deploy -##### Incorrect: `platformProxy` missing — Vite plugin ignores `CLOUDFLARE_ENV` - -```js title="astro.config.mjs" -adapter: cloudflare({ - // platformProxy not set -}), -``` - -```sh +# Development (uses env.development bindings) CLOUDFLARE_ENV=development astro build && wrangler deploy --env development -# ✗ platformProxy not configured — Vite plugin doesn't read CLOUDFLARE_ENV -# ✗ astro dev uses top-level (production) bindings -# ✗ Build may work but dev server has wrong bindings -``` - ---- - -##### Incorrect: `wrangler deploy --env` doesn't match build env - -```js title="astro.config.mjs" -adapter: cloudflare({ - platformProxy: { - environment: process.env.CLOUDFLARE_ENV, // "development" - }, -}), -``` - -```sh -CLOUDFLARE_ENV=development astro build && wrangler deploy --env production -# ✗ Build used "development" bindings (KV id: dev-kv-xyz789) -# ✗ Deploy targets "production" environment (expects prod-kv-abc123) -# ✗ Worker runs with dev bindings in production -``` - ---- - -##### Correct: hardcoded for single-environment projects - -If you only have one environment, hardcoding is fine: - -```js title="astro.config.mjs" -adapter: cloudflare({ - platformProxy: { - environment: 'production', // hardcoded - }, -}), -``` - -```sh -astro build && wrangler deploy -# ✓ Always uses production bindings -# ✓ No CLOUDFLARE_ENV needed ``` :::caution[Environment names must match] -The value of `CLOUDFLARE_ENV` must exactly match the `[env.]` section name in your wrangler config. If they don't match, the Vite plugin won't find the correct bindings during the build, and your Worker may fail to access KV namespaces, D1 databases, or other resources. +The value of `CLOUDFLARE_ENV` must exactly match the `[env.]` section name in your wrangler config. If they don't match, the Vite plugin won't find the correct bindings, and your Worker may fail to access KV namespaces, D1 databases, or other resources. ::: -#### Further reading - -
-Issues and PRs that contributed to this solution - -- [PR #11445](https://github.com/withastro/docs/pull/11445) — Added `platformProxy.environment` option docs -- [PR #13578](https://github.com/withastro/docs/pull/13578) — Added `CLOUDFLARE_ENV` variable docs -- [#15917](https://github.com/withastro/astro/issues/15917) — Users documented the three-way matching workaround -- [#16031](https://github.com/withastro/astro/issues/16031) — Same issue, suggested `cloudflareEnv` adapter option -- [#14540](https://github.com/withastro/astro/issues/14540) — Independent discovery of the same workaround -- [#13897](https://github.com/withastro/docs/issues/13897) — Misleading env vars documentation - -
- Learn how to update your [Cloudflare environments](https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/) in the [Migrate from wrangler dev guide](https://developers.cloudflare.com/workers/vite-plugin/reference/migrating-from-wrangler-dev/#cloudflare-environments). [astro-integration]: /en/guides/integrations/