feat: @clerk/shared getEnvVariable should support cloudflare:workers env for Cloudflare Workers runtimes

[Chat-JPTeasdale]

Description

@clerk/tanstack-react-start does not work on Cloudflare Workers because environment variables (CLERK_SECRET_KEY, CLERK_PUBLISHABLE_KEY) cannot be read at runtime. The shared getEnvVariable() function in @clerk/shared lacks a cloudflare:workers module env fallback, which means any framework package that relies on it (TanStack Start, Hono, etc.) fails to resolve Clerk env vars on CF Workers.

Environment

• Runtime: Cloudflare Workers (via @cloudflare/vite-plugin)
• Framework: TanStack Start v1.167+
• Clerk packages: @clerk/backend@3.x, @clerk/tanstack-react-start@1.x
• Bundler: Vite 7/8 with @cloudflare/vite-plugin

Problem

On Cloudflare Workers:

• process.env is not available (Workers are not Node.js)
• import.meta.env is statically replaced at build time by Vite — runtime values set via wrangler secret are not present
• globalThis[name] does not contain Worker env vars (they are passed via the fetch handler's env parameter)
• The cloudflare:workers module is available and exposes env vars set via dashboard/wrangler secrets

The current getEnvVariable() in @clerk/shared checks process.env, import.meta.env, context objects, and globalThis, but does not check cloudflare:workers. This means Clerk cannot find its secret key, publishable key, or any other env var when running on CF Workers.

Impact

This affects all Clerk framework packages that use getEnvVariable from @clerk/shared when deployed to Cloudflare Workers:

• @clerk/tanstack-react-start (TanStack Start on CF Workers)
• Any future framework integration targeting CF Workers

Additionally, @clerk/tanstack-react-start has SSR bundling issues on CF Workers — the React components (ClerkProvider, SignIn, SignUp) import browser-only APIs that fail during SSR bundling for the Workers runtime. The workaround is to use backend-only auth (@clerk/backend + verifyToken) and redirect to Clerk hosted pages for sign-in/sign-up. But even this backend-only approach requires getEnvVariable to resolve CLERK_SECRET_KEY from the Workers environment.

Prior Art

This was already fixed for Astro on Cloudflare in two PRs:

1. fix(astro): Fall back to process.env for runtime environment variables #7889 — fix(astro): Fall back to process.env for runtime environment variables
2. fix(astro): Restore Cloudflare Pages compatibility broken by cloudflare:workers env #8136 — fix(astro): Restore Cloudflare Pages compatibility broken by cloudflare:workers env

The Astro fix adds initCloudflareEnv() and a cloudflare:workers module check to packages/astro/src/server/get-safe-env.ts. However, this fix is Astro-specific — other framework packages that import getEnvVariable from @clerk/shared don't benefit from it.

Proposed Fix

PR #8196 adds the same cloudflare:workers env fallback to the shared getEnvVariable() function so all framework packages benefit:

#8196

Changes:

• initCloudflareWorkersEnv() — dynamically imports cloudflare:workers and caches the env object (identical pattern to Astro's initCloudflareEnv())
• getEnvVariable() — checks cloudflareWorkersEnv[name] before falling through to context-based checks
• Falls through when the key is missing (compatible with CF Pages where dashboard secrets may not be in the module env)
• Safe to call in non-Cloudflare environments — silently no-ops

Workaround

Until this is fixed, the workaround for Cloudflare Workers is to:

1. Use @clerk/backend directly (not the framework-specific package) for server-side auth
2. Manually pass env vars to createClerkClient({ secretKey: env.CLERK_SECRET_KEY }) from the Worker's env binding
3. Redirect to Clerk hosted pages for sign-in/sign-up (avoid SSR bundling issues with React components)

This works but bypasses the framework integration's automatic env resolution.

[JPTeasdale]

I’m JPTeasdale and I approve this message.

[Chat-JPTeasdale]

Two PRs submitted with different approaches to fix this:

1. feat(shared): Add cloudflare:workers env fallback to getEnvVariable #8196 — Shared-level fix: Adds cloudflare:workers env fallback directly to @clerk/shared's getEnvVariable(). Benefits all framework packages automatically.

2. feat(tanstack): Pass Cloudflare Workers env context to getEnvVariable #8198 — TanStack-level fix: Passes Cloudflare Workers env as context to getEnvVariable() in @clerk/tanstack-react-start, following the same pattern already used in @clerk/react-router. More targeted, follows existing conventions.

Both solve the same problem. They can be used individually or together for defense-in-depth.