Reference links:

• Starlight beta: withastro/starlight#3644
• Astro Docs example: withastro/docs#13230
• Astro migration guide
• Zod 4 migration guide
• Cloudflare adapter migration guide

• We do not use the @astrojs/cloudflare adapter. The site is compiled to static HTML and served by a custom Cloudflare Worker defined in worker/index.ts. The Cloudflare adapter migration guide does not apply here.
• We have six layers of Starlight customization documented in STARLIGHT_CUSTOMIZATIONS.md. This should be read beforehand. The most invasive is patch-package, which directly modifies Starlight files in node_modules after every install.
• We use several community Starlight plugins alongside the official ones.

Targets are determined by withastro/docs#13230. That is the north star.

The Starlight packages use pkg.pr.new URLs. These are preview builds cut directly from the PR branch, not published to npm.

Must be done in the final big-bang PR:

• astro/zod (the Astro 6 replacement for astro:schema) does not exist in Astro 5. The 18-file import rename must happen in the same commit as the version bump.
• experimental.contentIntellisense is still behind the experimental flag in Astro 5; it can only be removed once Astro 6 is installed.
• All patch-package patches are pinned to exact package version strings and must be regenerated against whatever versions the new packages install as.
• Zod 4 cannot be upgraded independently — it is bundled by Astro and upgrades with it.

Both of these are deprecated in Zod 4 but not removed. The old names still work at runtime; the only consequence is TypeScript deprecation warnings.

npx @astrojs/upgrade beta

This likely takes care of most Astro packages. Starlight package must be manually set to the PR.

npm install \
  @astrojs/starlight@https://pkg.pr.new/@astrojs/starlight@3644 \
  @astrojs/starlight-docsearch@https://pkg.pr.new/@astrojs/starlight-docsearch@3644 \
  @astrojs/starlight-tailwind@https://pkg.pr.new/@astrojs/starlight-tailwind@3644

Note on Vitest: vitest must stay at 3.2.x. vitest.workspace.ts uses getViteConfig() from astro/config, which Astro 6 only supports with Vitest v3.2. Vitest v4 is not yet supported.

See STARLIGHT_CUSTOMIZATIONS.md for full context on what each patch does. It's likely these patches don't work out the box for the new Starlight beta.

Open question: Why did we do this? This makes every upgrade nearly impossible.

All 18 files in src/schemas/ import z from "astro:schema". Astro 6 deprecates this virtual module in favor of "astro/zod".

-import { z } from "astro:schema";
+import { z } from "astro/zod";

Note: The zod code mod is likely useful.

Open question: Is there an Astro-specific code mod? Should there be?

Without a code mod:

find src/schemas -name "*.ts" | xargs sed -i '' 's|from "astro:schema"|from "astro/zod"|g'

Content Intellisense was behind an experimental flag in Astro 5 and is stable by default in Astro 6. The flag will either be silently ignored or cause a type error.

In astro.config.ts, remove:

experimental: {
  contentIntellisense: true,
},

File: astro.config.ts, vite.resolve.alias block

We shim Starlight's non-overridable Page.astro at the Vite bundler level:

vite: {
  resolve: {
    alias: {
      "./Page.astro": fileURLToPath(...),
      "../components/Page.astro": fileURLToPath(...),
    },
  },
},

Open question: Can we even keep doing such a low-level override? This likely wasn't exposed for a reason.