Feature: Add Astro 6 support to @keystatic/astro

[HoukasaurusRex]

Summary

@keystatic/astro@5.0.6 currently declares peerDependencies: { astro: "2 || 3 || 4 || 5" }, which means it does not support Astro 6.

When used with Astro 6, the Keystatic admin UI crashes with React hook errors:

TypeError: Cannot read properties of null (reading 'useState')
    at exports.useState
    at Keystatic

This appears to be caused by Astro 6 changes in how React islands are rendered/hydrated, resulting in Keystatic's React components running outside a proper React context tree.

Environment

• @keystatic/astro: 5.0.6
• @keystatic/core: 0.5.48
• astro: 6.0.4
• react: 19.2.4
• react-dom: 19.2.4

Workaround

Downgrading to Astro 5 resolves the issue since @keystatic/astro supports Astro 2-5.

Expected Behavior

@keystatic/astro should support Astro 6 and render the admin UI without React hook errors.

[Blboun3]

All is working for me, except pnpm complaining about unmet deps. Temporary fix for me was to add

"pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": [],
      "allowedVersions": {
        "@keystatic/astro>astro": "6"
      }
    }
  }

into my package.json, telling pnpm to ignore that the dependencies are unmet.
At least for my use cases everything seems to be working.

@keystatic/core: 0.5.48
@keystatic/astro: 5.0.6
astro: 6.0.4
react: 19.2.4
react-dom: 19.2.4

[SamLeatherdale]

@Blboun3 I would be interested to know more about under what circumstances it is working for you. I am trying to deploy Keystatic Cloud on Vercel, and the production /keystatic admin UI route does not work at all for me, just shows a blank screen.

After getting Cursor to investigate this further, I can confirm the issue is deeper than the React hook crashes above.

Error on Astro 6 (from Vercel build logs)

NoMatchingRenderer: Unable to render `Keystatic`.
No valid renderer was found for the `.js` file extension.
    at renderFrameworkComponent (file:///var/task/dist/server/chunks/entrypoint_Bh2Dr2yr.mjs:10944:15)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5) {
  loc: undefined,
  title: 'No matching renderer found.',
  hint: 'Did you mean to enable the `@astrojs/react`, `@astrojs/preact`, `@astrojs/solid-js`, `@astrojs/vue` or `@astrojs/svelte` integration?\n' +
    '\n' +
    'See https://docs.astro.build/en/guides/framework-components/ for more information on how to install and configure integrations.',
  frame: undefined,
  type: 'AstroError'
}

Root cause analysis

The issue is deeper than the React hook crashes described in the original report. When inspecting the built SSR chunk for the /keystatic/[...params] route, the Keystatic component is being passed as null to renderComponent:

renderComponent($$result, "Keystatic", null, { 
  "client:only": "react", 
  "client:component-hydration": "only", 
  "client:component-path": ".../@keystatic/astro/internal/keystatic-page.js", 
  "client:component-export": "Keystatic" 
})

The root cause is that virtual:keystatic-config — the Vite virtual module registered by the integration — is not being resolved and bundled into the SSR output under Astro 6's build pipeline.

The Vite plugin resolves the virtual module via this.resolve('./keystatic.config', './a'), which appears to only work in the Vite dev context, not in Astro 6's final SSR bundle.

A file extension patch (.js → .jsx in keystatic-astro-page.astro) changes the initial error message but doesn't fix the underlying problem — the export is still null at runtime because the virtual module resolution fails at build time.

Note: the error does not appear in astro dev because Vite's dev server resolves virtual modules much more permissively than the production build pipeline. This makes it easy to miss during local development.

Workaround

Downgrade to Astro 5 with compatible integration versions. Everything works correctly on Astro 5.

Environment

Before (broken):

• astro: 6.0.8
• @astrojs/react: 5.0.1
• @astrojs/markdoc: 1.0.2
• @astrojs/vercel: 10.0.2
• @keystatic/astro: 5.0.6
• @keystatic/core: 0.5.48
• react: 19.2.4

After (working):

• astro: 5.18.1
• @astrojs/react: 4.4.2
• @astrojs/markdoc: 0.15.11
• @astrojs/vercel: 8.2.11

[Blboun3]

@SamLeatherdale not knowing it wasn't supported I just installed it after installing astro 6 (keystatic/core and keystatic/astro like you would, except I had to ignore the dependencies, then I defined quite basic collection in keystatic.config.ts. And then I just run pnpm run dev (package.json-ed to astro dev) and open it in Firefox based browser (if that might have any effect?) and it just works ? The only issue I had in the beginning when it was ignoring the written files but that was due to my .gitignore (didn't know that keystatic respected .gitignores as its own ignores also)

So yeah, for me it just works, I guess the best I can do is provide my package.json:

{
  "name": "<censred>-web",
  "type": "module",
  "version": "0.0.1",
  "engines": {
    "node": ">=22.12.0"
  },
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/markdoc": "^1.0.0",
    "@astrojs/mdx": "^5.0.0",
    "@astrojs/node": "^10.0.1",
    "@astrojs/react": "^5.0.0",
    "@iconify-json/fa6-regular": "^1.2.4",
    "@iconify-json/fa6-solid": "^1.2.4",
    "@iconify/utils": "^3.1.0",
    "@keystatic/astro": "^5.0.6",
    "@keystatic/core": "^0.5.48",
    "@tailwindcss/vite": "^4.2.1",
    "@types/react": "^19.2.14",
    "@types/react-dom": "^19.2.3",
    "astro": "^6.0.4",
    "astro-icon": "^1.1.5",
    "better-sqlite3": "^12.8.0",
    "ics": "^3.8.1",
    "react": "^19.2.4",
    "react-dom": "^19.2.4",
    "tailwindcss": "^4.2.1"
  },
  "devDependencies": {
    "@astrojs/check": "^0.9.7",
    "@types/better-sqlite3": "^7.6.13",
    "typescript": "^5.9.3"
  },
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": [],
      "allowedVersions": {
        "@keystatic/astro>astro": "6"
      }
    }
  }
}

Edit: I've not tested in prod tho, only in dev, if that might be the difference?

[SamLeatherdale]

@Blboun3 Yep, I think that's the problem, it works fine for me on dev, but it only fails on prod.

What platform do you deploy to in production? Do you use Keystatic in GitHub or Cloud mode, or just in local mode on your own machine?

[Thomas-Digitals-02]

+1 here , I’m running into the same issue while trying to upgrade a set of Astro-based templates that rely on Keystatic.

For my use case, the admin UI working reliably in production is critical (these templates are used by non-technical users), so I’m currently holding on Astro v5 for stability.

Would appreciate any updates on Astro v6 compatibility or guidance on a safe upgrade path when available. Happy to help test if needed.

[Blboun3]

@SamLeatherdale sorry for taking a bit longer to respond, but today I've tested it in "dev-prod" as well (pnpm run build and then HOST=0.0.0.0 ORIGIN=http://localhost:4321 node dist/server/entry.mjs, running locally but the built thing, which is how the production will be run) and it still seems to be working ? I can access it without any issues, create new post, edit it, delete it. I've not updated anything since my original response

[TekGadgt]

I was having this issue as well. Took a crack at resolving it with Claude Code assistance, and found the issue is actually super minor.

Workaround: .tsx wrapper for the Keystatic admin page

The root cause is that Astro's React renderer doesn't match .js file extensions when resolving framework components in the SSR bundle. Keystatic's internal keystatic-page.js uses client:only="react", but because it's a .js file, Astro throws NoMatchingRenderer at runtime on hosts like Netlify.

This works in dev because Vite handles modules differently than the production SSR bundle.

The fix is two files:

src/components/KeystaticApp.tsx

import { makePage } from '@keystatic/astro/ui';
import config from '../../keystatic.config';

export const KeystaticApp = makePage(config);

src/pages/keystatic/[...params].astro

export const prerender = false;
import { KeystaticApp } from '../../components/KeystaticApp.tsx';


<KeystaticApp client:only="react" />

This is functionally identical to what the integration injects — just with a .tsx extension so Astro correctly maps it to the React renderer.

Note: This will produce a route collision warning since the integration still injects its own /keystatic/[...params] route. The local page takes priority so it works fine, but Astro has warned this will become a hard error in a future version. To eliminate the warning, you can replace the keystatic() integration with a custom one that only injects the API route — happy to share that if anyone needs it.

Tested with Astro 6.1.2, @keystatic/astro 5.0.6, @astrojs/netlify 7.0.5, output: 'static'.