docs: correct the browser envName() fallback (development, not production)

[rqbazan]

What

Three docs pages and the __ENV_NAME__ JSDoc claimed that, without the envConfig() Vite plugin, envName() in browser code falls back to "production". That is wrong — it's only true on the server.

Why it's wrong

In the browser, envName()'s readEnv() reads only window.__env (or the <EnvScript /> tag) — never process.env or import.meta.env. So in a pure SPA, neither NODE_ENV nor VITE_ENV is visible, and with no plugin (no __ENV_NAME__) every entry in the precedence chain is empty:

env.ENV → __ENV_NAME__ → env.NODE_ENV → env.VITE_ENV → "development"
  ∅           ∅              ∅               ∅          ← falls through here

envName() falls through to its "development" fallback — silently shipping the dev config to every environment — regardless of the --mode or VITE_ENV used at build time. Verified empirically: VITE_ENV=production vite build without the plugin still resolves development in the browser; __ENV_NAME__ is left as a bare identifier (no define), so buildTimeEnvName() returns undefined.

This is exactly the trap it sounds like: a build that works locally (where development is what you want) quietly mis-targets in production.

Changes

• concepts/env-name.mdx — fix the precedence note (item 2) and the "Vite gotcha" section.
• guides/custom-modes.mdx — fix the "The problem" framing.
• guides/spa-dynamic-import.mdx — fix the envConfig() plugin rationale bullet.
• package/src/lib/const.ts — tighten the __ENV_NAME__ JSDoc (shipped with the package), hence the patch changeset.

The reframe throughout: the plugin is required for any non-development browser build, not just custom modes like staging/qa. The examples were already correct (spa-vite-dynamic and spa-vite-plugin both wire envConfig()); only the prose was misleading.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	vlandoss-env-docs	995ef13	Commit Preview URL Branch Preview URL	Jun 17 2026, 03:08 AM