fix(astro): Fix compatibility with Astro v6 Cloudflare adapter by alexcarpenter · Pull Request #7890 · clerk/javascript

alexcarpenter · 2026-02-19T20:01:07Z

Astro v6's Cloudflare adapter removed locals.runtime.env, which causes @clerk/astro to crash. This adds a fallback that imports env from cloudflare:workers when locals.runtime.env is unavailable, while maintaining backwards compatibility with Astro v4/v5.

Description

fixes #7849

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Adds compatibility with Astro v6 Cloudflare adapter.
Bug Fixes
- More robust environment detection with safe fallbacks to prevent runtime failures on Astro v6 + Cloudflare.
Tests
- New tests covering environment initialization, caching/memoization, and fallback precedence across Astro versions.

Astro v6's Cloudflare adapter removed `locals.runtime.env`, which causes `@clerk/astro` to crash. This adds a fallback that imports env from `cloudflare:workers` when `locals.runtime.env` is unavailable, while maintaining backwards compatibility with Astro v4/v5. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

changeset-bot · 2026-02-19T20:01:11Z

🦋 Changeset detected

Latest commit: 3c68b4d

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

This PR includes changesets to release 1 package

Name	Type
@clerk/astro	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 · 2026-02-19T20:01:12Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Skipped		Feb 19, 2026 8:32pm

pkg-pr-new · 2026-02-19T20:05:03Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7890

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7890

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7890

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7890

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7890

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7890

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7890

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7890

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7890

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7890

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@7890

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7890

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7890

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7890

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7890

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7890

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7890

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7890

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7890

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7890

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7890

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7890

commit: 3c68b4d

coderabbitai · 2026-02-19T20:07:14Z

📝 Walkthrough

Walkthrough

Adds Astro v6 compatibility for the Cloudflare adapter: broadens the astro peerDependency to include ^6.0.0, makes Locals.runtime optional, introduces initCloudflareEnv() and a cached Cloudflare env detection mechanism, updates environment resolution to prefer locals.runtime.env but fall back to the Cloudflare workers env (and import.meta.env) when locals.runtime.env is absent or throws, and calls initCloudflareEnv() from the Astro middleware during request handling. Tests for get-safe-env and caching/precedence behavior were added.

Possibly related issues

clerk/javascript issue 7849 — Implements the Cloudflare Workers env fallback, caching, and middleware init logic to address Astro v6 errors when locals.runtime.env is unavailable.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: fixing Astro v6 Cloudflare adapter compatibility, which aligns with the PR's core objective to address the removal of locals.runtime.env in Astro v6.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

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

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/astro/src/server/get-safe-env.ts`:
- Around line 6-32: Add unit tests covering the Cloudflare env fallback: write
tests for initCloudflareEnv, the cached cloudflareEnv value, and
getContextEnvVar's fallback behavior when cloudflare:workers is present and when
it throws. In one test mock dynamic import of the moduleName
'cloudflare:workers' to return an object with env (e.g., {env: {KEY: "value"}}),
call initCloudflareEnv() and assert cloudflareEnv is set and
getContextEnvVar('KEY') returns the mocked value; in another test mock the
dynamic import to throw, call initCloudflareEnv(), assert cloudflareEnv becomes
null and getContextEnvVar('KEY') falls back to the non-Cloudflare path. Ensure
tests reset/clear the cloudflareEnv cache between cases so caching behavior is
validated.

coderabbitai · 2026-02-19T20:07:17Z

packages/astro/src/server/get-safe-env.ts

+/**
+ * Cached env object from `cloudflare:workers` for Astro v6+ Cloudflare adapter.
+ * - `undefined`: not yet attempted
+ * - `null`: attempted but not available (non-Cloudflare environment)
+ * - object: the env object from `cloudflare:workers`
+ */
+let cloudflareEnv: Record<string, string> | null | undefined;
+
+/**
+ * @internal
+ * Attempts to import env from `cloudflare:workers` and caches the result.
+ * This is needed for Astro v6+ where `locals.runtime.env` is no longer available.
+ * Safe to call in non-Cloudflare environments — will no-op.
+ */
+async function initCloudflareEnv(): Promise<void> {
+  if (cloudflareEnv !== undefined) {
+    return;
+  }
+  try {
+    // Use a variable to prevent TypeScript from resolving the module specifier
+    const moduleName = 'cloudflare:workers';
+    const mod = await import(/* @vite-ignore */ moduleName);
+    cloudflareEnv = mod.env;
+  } catch {
+    cloudflareEnv = null;
+  }
+}


⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash # Check whether any tests were changed in this PR git diff --name-only origin/main...HEAD | rg -i '(__tests__|test|spec)\.(ts|tsx|js|jsx)$' # Search for existing tests covering the new Cloudflare env fallback path rg -n 'initCloudflareEnv|getContextEnvVar|cloudflare:workers' \ -g '**/__tests__/**' -g '*.{test,spec}.{ts,tsx,js,jsx}' 2>/dev/null || true

Repository: clerk/javascript

Length of output: 100

🏁 Script executed:

#!/bin/bash # Find the packages/astro directory and look for test files find packages/astro -type f $ -name '*.test.ts' -o -name '*.test.tsx' -o -name '*.spec.ts' -o -name '*.spec.tsx' -o -path '*/__tests__/*' $ | head -20 # Also check the structure of the packages/astro directory echo "=== packages/astro structure ===" find packages/astro -type d | head -20 # Search across all test files for cloudflare-related tests echo "=== Searching for cloudflare env tests ===" rg 'cloudflare.*env|initCloudflareEnv' --type ts --type tsx 2>/dev/null || echo "No matches found" # Look for getContextEnvVar or get-safe-env related tests echo "=== Searching for get-safe-env tests ===" rg 'getSafeEnv|getContextEnvVar|get-safe-env' --type ts --type tsx 2>/dev/null | head -20 || echo "No matches found"

Repository: clerk/javascript

Length of output: 995

🏁 Script executed:

#!/bin/bash # Read the complete get-safe-env.ts file echo "=== packages/astro/src/server/get-safe-env.ts ===" cat packages/astro/src/server/get-safe-env.ts echo "" echo "=== Checking if any test files import get-safe-env ===" rg 'get-safe-env|getSafeEnv' packages/astro/src --type ts --type tsx echo "" echo "=== Contents of the existing test file ===" cat packages/astro/src/internal/__tests__/create-clerk-instance.test.ts | head -100

Repository: clerk/javascript

Length of output: 8030

Add tests for the Cloudflare env fallback logic.

The new initCloudflareEnv() function and the cloudflareEnv fallback path in getContextEnvVar() (lines 20–33 and 47–50) lack test coverage. Add tests to verify that the fallback correctly imports from cloudflare:workers in Cloudflare environments and gracefully handles non-Cloudflare environments.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed. In `@packages/astro/src/server/get-safe-env.ts` around lines 6 - 32, Add unit tests covering the Cloudflare env fallback: write tests for initCloudflareEnv, the cached cloudflareEnv value, and getContextEnvVar's fallback behavior when cloudflare:workers is present and when it throws. In one test mock dynamic import of the moduleName 'cloudflare:workers' to return an object with env (e.g., {env: {KEY: "value"}}), call initCloudflareEnv() and assert cloudflareEnv is set and getContextEnvVar('KEY') returns the mocked value; in another test mock the dynamic import to throw, call initCloudflareEnv(), assert cloudflareEnv becomes null and getContextEnvVar('KEY') falls back to the non-Cloudflare path. Ensure tests reset/clear the cloudflareEnv cache between cases so caching behavior is validated.

jacekradko

Some tests would be nice, but the functionality looks good

wobsoriano

Thanks for catching this!

github-actions bot added astro core-3 labels Feb 19, 2026

vercel bot deployed to Preview February 19, 2026 20:01 View deployment

coderabbitai bot reviewed Feb 19, 2026

View reviewed changes

jacekradko approved these changes Feb 19, 2026

View reviewed changes

Create get-safe-env.test.ts

467fcc4

alexcarpenter force-pushed the fix/astro-v6-cloudflare-compat branch from 160b887 to 467fcc4 Compare February 19, 2026 20:21

vercel bot temporarily deployed to Preview February 19, 2026 20:21 Inactive

wobsoriano approved these changes Feb 19, 2026

View reviewed changes

Update get-safe-env.test.ts

3c68b4d

vercel bot temporarily deployed to Preview February 19, 2026 20:32 Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

fix(astro): Fix compatibility with Astro v6 Cloudflare adapter#7890

fix(astro): Fix compatibility with Astro v6 Cloudflare adapter#7890
alexcarpenter wants to merge 3 commits intomainfrom
fix/astro-v6-cloudflare-compat

alexcarpenter commented Feb 19, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

vercel bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Feb 19, 2026 •

edited

Loading

Walkthrough

Possibly related issues

Uh oh!

coderabbitai bot left a comment

Uh oh!

coderabbitai bot Feb 19, 2026

Uh oh!

jacekradko left a comment

Uh oh!

wobsoriano left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

alexcarpenter commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Possibly related issues

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

jacekradko left a comment

Choose a reason for hiding this comment

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexcarpenter commented Feb 19, 2026 •

edited

Loading

changeset-bot bot commented Feb 19, 2026 •

edited

Loading

vercel bot commented Feb 19, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 19, 2026 •

edited

Loading

coderabbitai bot commented Feb 19, 2026 •

edited

Loading