docs: add multi-environment Cloudflare deployment guide

[lifeforcedev]

Summary

Adds documentation for the three-way matching requirement when deploying to multiple Cloudflare environments with @astrojs/cloudflare.

Environment

Tested with:

• Astro 6.x
• @astrojs/cloudflare v13.x
• Cloudflare Workers with nodejs_compat compatibility flag
• Wrangler latest

What's Missing from Current Docs

The current docs mention CLOUDFLARE_ENV but don't explain:

1. The platformProxy: { environment: process.env.CLOUDFLARE_ENV } adapter config
2. The matching [env.<name>] section in wrangler.toml
3. Why environment names must match exactly

Changes

Added "Multi-environment deployments with platformProxy" section with:

• Three-way matching explanation
• Complete code example for astro.config.mjs and wrangler.toml
• Build commands for production and development
• Caution note about matching environment names

---

Extended Examples (for reference)

Correct: all three match

CLOUDFLARE_ENV=production — everything uses production:

adapter: cloudflare({
  platformProxy: {
    environment: process.env.CLOUDFLARE_ENV, // "production"
  },
}),

{
  "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" }
    ]
  }
}

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:

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

{
  "env.production": { ... },
  "env.development": { ... }
  // No "env.staging" section
}

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

adapter: cloudflare({
  // platformProxy not set
}),

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

adapter: cloudflare({
  platformProxy: {
    environment: process.env.CLOUDFLARE_ENV, // "development"
  },
}),

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

adapter: cloudflare({
  platformProxy: {
    environment: 'production', // hardcoded
  },
}),

astro build && wrangler deploy
# ✓ Always uses production bindings
# ✓ No CLOUDFLARE_ENV needed

---

Sources

• PR #11445 — Added platformProxy.environment option docs
• PR #13578 — Added CLOUDFLARE_ENV variable docs
• #15917 — Users documented the three-way matching workaround
• #16031 — Same issue, suggested cloudflareEnv adapter option
• #14540 — Independent discovery of the same workaround
• #13897 — Misleading env vars documentation
• #16040 — Same issue, pointed to workaround

Related Issues

Closes #15917, #16031, #16040, #14540, #13897

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	60aef69
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a22ef21eea4900008783d51
😎 Deploy Preview	https://deploy-preview-13995--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/integrations-guide/cloudflare.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.