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

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>

Author: alexcarpenter

.changeset/fix-astro-v6-cloudflare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': patch
+---
+
+Fix compatibility with Astro v6 Cloudflare adapter by using `cloudflare:workers` env when `locals.runtime.env` is unavailable

packages/astro/package.json

@@ -100,7 +100,7 @@
     "astro": "^5.17.1"
   },
   "peerDependencies": {
-    "astro": "^4.15.0 || ^5.0.0"
+    "astro": "^4.15.0 || ^5.0.0 || ^6.0.0"
   },
   "engines": {
     "node": ">=20.9.0"

packages/astro/src/env.d.ts

@@ -30,7 +30,7 @@ interface ImportMeta {
 
 declare namespace App {
   interface Locals {
-    runtime: { env: InternalEnv };
+    runtime?: { env: InternalEnv };
     keylessClaimUrl?: string;
     keylessApiKeysUrl?: string;
     keylessPublishableKey?: string;

packages/astro/src/server/clerk-middleware.ts

@@ -28,7 +28,7 @@ import { canUseKeyless } from '../utils/feature-flags';
 import { buildClerkHotloadScript } from './build-clerk-hotload-script';
 import { clerkClient } from './clerk-client';
 import { createCurrentUser } from './current-user';
-import { getClientSafeEnv, getSafeEnv } from './get-safe-env';
+import { getClientSafeEnv, getSafeEnv, initCloudflareEnv } from './get-safe-env';
 import { resolveKeysWithKeylessFallback } from './keyless/utils';
 import { serverRedirectWithAuth } from './server-redirect-with-auth';
 import type {
@@ -79,6 +79,8 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
       return next();
     }
 
+    await initCloudflareEnv();
+
     const clerkRequest = createClerkRequest(context.request);
 
     // Resolve keyless URLs per-request in development

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

@@ -3,15 +3,53 @@ import type { APIContext } from 'astro';
 
 type ContextOrLocals = APIContext | APIContext['locals'];
 
+/**
+ * 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;
+  }
+}
+
 /**
  * @internal
  * Isomorphic handler for reading environment variables defined from Vite or are injected in the request context (CF Pages)
  */
 function getContextEnvVar(envVarName: keyof InternalEnv, contextOrLocals: ContextOrLocals): string | undefined {
   const locals = 'locals' in contextOrLocals ? contextOrLocals.locals : contextOrLocals;
 
-  if (locals?.runtime?.env) {
-    return locals.runtime.env[envVarName];
+  // Astro v4/v5 Cloudflare adapter: env is on locals.runtime.env
+  try {
+    if (locals?.runtime?.env) {
+      return locals.runtime.env[envVarName];
+    }
+  } catch {
+    // Astro v6 Cloudflare adapter throws when accessing locals.runtime.env
+  }
+
+  // Astro v6 Cloudflare adapter: env from cloudflare:workers
+  if (cloudflareEnv) {
+    return cloudflareEnv[envVarName];
   }
 
   return import.meta.env[envVarName];
@@ -72,4 +110,4 @@ function getClientSafeEnv(context: ContextOrLocals) {
   };
 }
 
-export { getSafeEnv, getClientSafeEnv };
+export { getSafeEnv, getClientSafeEnv, initCloudflareEnv };