Cloudflare adapter (Astro 6): /api/keystatic/* crashes with 'Astro.locals.runtime.env has been removed in Astro v6'

[peppir]

Summary

With @astrojs/cloudflare on Astro 6, @keystatic/astro's GitHub-mode API routes
(/api/keystatic/*, e.g. github/login) crash at runtime with:

Error: Astro.locals.runtime.env has been removed in Astro v6. Use 'import { env } from "cloudflare:workers"' instead.
    at get env (chunks/worker-entry_....mjs:19512:15)
    at Module.keystaticAPIRoute (chunks/keystatic-api_....mjs:821:213)
    at renderEndpoint (chunks/worker-entry_....mjs:1053:32)
    at PagesHandler.handle (chunks/worker-entry_....mjs:4259:26)

This reproduces both in astro dev (with the Cloudflare adapter active) and on a real
deployed Cloudflare Worker (captured via wrangler tail). GitHub-mode credentials
(KEYSTATIC_GITHUB_CLIENT_ID/SECRET, KEYSTATIC_SECRET) are correctly configured —
the crash happens once the API handler tries to read the Cloudflare runtime env to get
at those values.

Filed as requested by @emmatown in #1515 ("please open a new issue with ... where the
issue occurs") — this is a different, Cloudflare-specific failure than the
NoMatchingRenderer issue discussed there.

Environment

• astro: 6.4.8
• @astrojs/cloudflare: 13.7.0
• @astrojs/react: 6.0.1
• @keystatic/astro: 5.1.0
• @keystatic/core: 0.5.50
• react / react-dom: 19.2.7
• wrangler: 4.108.0
• Storage mode: github

Steps to reproduce

1. Astro 6 project with output: 'static' + adapter: cloudflare().
2. Add keystatic() to integrations, with storage: { kind: 'github', repo: ... } in
   keystatic.config.ts and valid KEYSTATIC_GITHUB_CLIENT_ID / _CLIENT_SECRET /
   KEYSTATIC_SECRET env vars.
3. Run astro dev (or deploy via wrangler deploy) and hit /api/keystatic/github/login
   (or complete the GitHub OAuth flow via /keystatic).
4. Request fails with the error above (500 in production, similar in dev).

Related prerequisite issue (same setup)

Before reaching the above, wiring keystatic() under @astrojs/cloudflare on Astro 6
also crashes with module is not defined inside react/index.js, because
@astrojs/cloudflare's own SSR/workerd optimizeDeps defaults don't include react/
react-dom, so the raw CJS build reaches workerd unbundled. Adding this to the user's
own vite config works around it (the adapter merges user optimizeDeps.include into
its SSR environment config):

vite: {
  optimizeDeps: {
    include: ['react', 'react-dom', 'react/jsx-runtime', 'react-dom/server', 'react-dom/server.edge'],
  },
},

Mentioning this since it's a prerequisite to even reach the locals.runtime.env crash
above, and other Cloudflare+Astro 6 users will likely hit it first.

Expected behavior

Keystatic's GitHub-mode API handler should read the Cloudflare Workers runtime env via
import { env } from 'cloudflare:workers' (or accept it through its existing
adapter-provided context/locals) instead of the removed Astro.locals.runtime.env,
so GitHub-mode works under Astro 6 + @astrojs/cloudflare.

[pauldiv]

Hit this exact issue building a portfolio site on @astrojs/cloudflare (Astro 7.0.9, @keystatic/astro 5.2.0, @keystatic/core 0.5.51, wrangler 4.110.0) — same crash, same Astro.locals.runtime.env has been removed message, in both astro dev and a real deployed Worker (confirmed via wrangler tail).

Patch that fixed it for us

The fix is exactly what the removed API's own error message suggests. keystatic-astro-api.js currently reads the Cloudflare env via context.locals.runtime?.env:

const envVarsForCf = (_context$locals = context.locals) === null || _context$locals === void 0 || (_context$locals = _context$locals.runtime) === null || _context$locals === void 0 ? void 0 : _context$locals.env;

Replacing that with a dynamic cloudflare:workers import fixes it:

async function getCloudflareEnvVars() {
  try {
    const cf = await import('cloudflare:workers');
    return cf.env;
  } catch {
    return undefined;
  }
}
// ...
const envVarsForCf = await getCloudflareEnvVars();

(wrapped in try/catch so it doesn't break other adapters where cloudflare:workers isn't a valid specifier — this file is shared across all Astro adapters, not Cloudflare-specific)

We applied this via patch-package rather than waiting. Full patch (against node_modules/@keystatic/astro/dist/keystatic-astro-api.js):

--- a/node_modules/@keystatic/astro/dist/keystatic-astro-api.js
+++ b/node_modules/@keystatic/astro/dist/keystatic-astro-api.js
@@ -1,10 +1,23 @@
 import { makeGenericAPIRouteHandler } from '@keystatic/core/api/generic';
 import { parseString } from 'set-cookie-parser';
 
+async function getCloudflareEnvVars() {
+  try {
+    const cf = await import('cloudflare:workers');
+    return cf.env;
+  } catch {
+    return undefined;
+  }
+}
+
 function makeHandler(_config) {
   return async function keystaticAPIRoute(context) {
-    var _context$locals, _ref, _config$clientId, _ref2, _config$clientSecret, _ref3, _config$secret;
-    const envVarsForCf = (_context$locals = context.locals) === null || _context$locals === void 0 || (_context$locals = _context$locals.runtime) === null || _context$locals === void 0 ? void 0 : _context$locals.env;
+    var _ref, _config$clientId, _ref2, _config$clientSecret, _ref3, _config$secret;
+    const envVarsForCf = await getCloudflareEnvVars();
     const handler = makeGenericAPIRouteHandler({
       ..._config,
       clientId: (_ref = (_config$clientId = _config.clientId) !== null && _config$clientId !== void 0 ? _config$clientId : envVarsForCf === null || envVarsForCf === void 0 ? void 0 : envVarsForCf.KEYSTATIC_GITHUB_CLIENT_ID) !== null && _ref !== void 0 ? _ref : tryOrUndefined(() => {

Second, related issue worth flagging here too

Even after this fix, we found the GitHub App creation wizard (/keystatic → guided setup) doesn't work under this same adapter combo — it only activates when NODE_ENV === 'development' and storage.kind === 'github', and reaching that locally hits the module is not defined bundling issue mentioned in the "Related prerequisite issue" section above (same root cause: optimizeDeps not including react/react-dom for the workerd SSR environment). We worked around it entirely by creating the GitHub App manually via GitHub's own form (exact permissions pulled from keystatic-core-ui.js's manifest object: Contents read/write, Metadata read-only, Pull requests read-only, callback URL /api/keystatic/github/oauth/callback) rather than chasing the wizard further. Mentioning in case it saves someone else the detective work — happy to open a separate issue for this one specifically if that's more useful than lumping it in here.

Thanks for maintaining this — happy to open a PR with the cloudflare:workers fix if that'd be welcome.