feat(tanstack): Pass Cloudflare Workers env context to getEnvVariable

[Chat-JPTeasdale]

Description

Alternative approach to #8196 — instead of adding cloudflare:workers support to the shared getEnvVariable, this PR fixes the issue at the TanStack Start package level by passing Cloudflare Workers env as context to getEnvVariable(), following the same pattern already used in @clerk/react-router.

Related issue: #8197

Problem

On Cloudflare Workers, @clerk/tanstack-react-start calls getEnvVariable('CLERK_SECRET_KEY') without a context parameter:

// packages/tanstack-react-start/src/server/constants.ts
SECRET_KEY: getEnvVariable('CLERK_SECRET_KEY'),  // no context!

Compare with @clerk/react-router which correctly passes context:

// packages/react-router/src/server/loadOptions.ts
const secretKey = getEnvVariable('CLERK_SECRET_KEY', context);  // ✅ passes context

Without context, getEnvVariable cannot find env vars on CF Workers because process.env and import.meta.env are not available at runtime.

Solution

1. cloudflareEnv.ts — New module that dynamically imports cloudflare:workers and caches the env object (same pattern as @clerk/astro's initCloudflareEnv)
2. clerkMiddleware.ts — Calls initCloudflareWorkerEnv() at the start of the middleware (no-op on non-CF runtimes)
3. constants.ts — commonEnvs() now accepts optional context and passes it to all getEnvVariable() calls
4. utils/env.ts — getPublicEnvVariables() now accepts optional context

How this differs from #8196

Approach	PR #8196 (shared)	This PR (tanstack)
Scope	All framework packages	TanStack Start only
Changes	@clerk/shared	@clerk/tanstack-react-start
Pattern	Auto-import cloudflare:workers in shared	Pass context like @clerk/react-router does
Risk	Lower — additive fallback	Lower — follows existing React Router pattern

Both PRs solve the same problem. The Clerk team can choose which approach they prefer, or merge both for defense-in-depth.

Checklist

• Follows existing @clerk/react-router pattern for CF context passing
• Safe on non-Cloudflare runtimes (init silently no-ops)
• No breaking changes (context parameter is optional)

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation

Summary by CodeRabbit

• New Features
  • Added support for Cloudflare Workers environment variable resolution in TanStack React Start, enabling proper runtime access to secret keys and configuration values on Cloudflare Workers deployments.

[changeset-bot]

🦋 Changeset detected

Latest commit: 34b89fa

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/tanstack-react-start	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

@ChatJPTeasdale is attempting to deploy a commit to the Clerk Production Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 99e4983d-ee3e-41d8-aa7d-058c357c10fd

📥 Commits

Reviewing files that changed from the base of the PR and between abbc6c4 and 34b89fa.

📒 Files selected for processing (5)

• .changeset/tanstack-cloudflare-env-context.md
• packages/tanstack-react-start/src/server/clerkMiddleware.ts
• packages/tanstack-react-start/src/server/cloudflareEnv.ts
• packages/tanstack-react-start/src/server/constants.ts
• packages/tanstack-react-start/src/utils/env.ts

---

📝 Walkthrough

Walkthrough

This PR adds Cloudflare Workers environment variable support to the @clerk/tanstack-react-start package. A new module provides async initialization and synchronous access to Cloudflare Workers env context. The clerk middleware calls this initializer at startup. Environment variable resolution functions throughout the package are updated to accept and propagate a context parameter, enabling Clerk environment variables like CLERK_SECRET_KEY to be resolved through Cloudflare Workers' env context at runtime instead of relying on process.env/import.meta.env.

Possibly related issues

• feat: @clerk/shared getEnvVariable should support cloudflare:workers env for Cloudflare Workers runtimes #8197 — Addresses the same Cloudflare Workers environment variable resolution gap by providing a runtime path through which Clerk environment variables can be resolved on Cloudflare Workers where standard Node.js/browser env mechanisms are unavailable.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: passing Cloudflare Workers env context through the TanStack Start package's environment resolution, which is the primary objective of this PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}