Repository navigation
docs: Astro 5 → 7 upgrade tracker (apps/docs) #115
Description
Activity
Audit note (scheduled routine): the gating blocker on this tracker has cleared, and the target has actually moved past it.
Ecosystem state as of today:
@astrojs/starlight@0.40.0(2026-06-09) shipped with a minimum ofastro ^6.4.5— the "no Starlight release supports Astro 6 yet" blocker at the top of this issue is no longer true.@astrojs/starlight@0.41.0(2026-06-23) dropped Astro 6 support and now requiresastro ^7.- Latest Starlight is
0.41.3; Astro 7 is generally available.
Two ways to re-scope this ticket:
- Land the migration as-planned (Astro 6) — pin
@astrojs/starlightto the^0.40.xwindow, bumpastroto^6.x. Buys us the docs upgrade now, but immediately becomes stale because the ecosystem is on Astro 7. - Re-target to Astro 7 — bump straight to
@astrojs/starlight@^0.41+astro@^7. Skips a hop, matches where the ecosystem is, single migration.
Recommendation: (2). The migration shape in the original description mostly still applies (
@astrojs/tailwind→ Vite Tailwind plugin, content-collectionzodv4 audit, custom Vite plugin sanity check); the only extra beat is verifyingastro-expressive-codeandpagefindagainst Astro 7.If you're happy with (2), I can rename this to "Astro 7 upgrade tracker (apps/docs)" and update the acceptance criteria to match. Ping me if you'd rather I do the migration itself in a PR.
Generated by Claude Code
Audit update (scheduled routine): the "blocked on Starlight" premise no longer holds. Retracing upstream since this ticket was filed:
Starlight release Date peerDependencies.astro0.39.x 2026-05-07 → 2026-06-02 still ^5(matches this ticket)0.40.0 2026-06-09 ^6.4.5← Astro 6 support landed0.41.0 2026-06-23 ^7.0.2← already jumped past 60.41.3 (current) 2026-07-03 ^7.0.2Current pin in
apps/docs/package.jsonis@astrojs/starlight@^0.33.0onastro@^5.7.0, so the workspace is now four minors behind Starlight and up to two majors behind Astro. Two paths from here:- Two-step:
astro@6first, then@7later. Matches the migration shape in the original ticket but does the upgrade twice. - Jump straight to
astro@7+@astrojs/starlight@0.41.3. Larger diff to validate, but avoids landing an intermediate state that upstream has already moved past.
Either way, the tracker no longer waits on Starlight. Other blockers from the original ticket to re-verify against current versions:
@astrojs/tailwind@6.0.2peer-deps^3 || ^4 || ^5— still incompatible with Astro 6/7; needs the Tailwind v4 +@tailwindcss/viteswap the ticket already calls out.zodbump from v3 to v4 transitively via Astro 6+ —apps/docs/package.jsoncurrently pinszod: 3.25.76explicitly, so a workspace-wide zod story needs sorting before this can land cleanly.
Not touching #110 or filing PRs from this audit — flagging so the tracker can be re-scoped ("Astro 5 → Astro 7 direct" vs a two-step migration) and the Dependabot ignore rule can be tightened to
^7once decided.
Generated by Claude Code
- Two-step:
Audit note (scheduled routine): the Starlight blocker cited above is no longer valid — refreshed the npm registry against latest and the migration is now actionable.
Current upstream state (verified against
registry.npmjs.orgtoday):Package Version Peer of interest Status vs this tracker @astrojs/starlight0.41.4astro: ^7.0.2✅ Astro 7 supported (was ^5.1.5when this issue was filed)@astrojs/starlight-tailwind5.0.0@astrojs/starlight: >=0.38.0,tailwindcss: ^4.0.0✅ Tailwind v4 compatible @astrojs/tailwind6.0.2astro: ^3 || ^4 || ^5❌ Still Astro-5-only, no v7 support; upstream continues to point to the Vite Tailwind v4 plugin instead Repo currently pins
@astrojs/starlight@^0.33.0,astro@^5.7.0,@astrojs/tailwind@^6.0.0inapps/docs/package.json:1— i.e. this tracker's world.Refreshed migration shape (supersedes the original plan):
@astrojs/starlight→^0.41.4(drops the Astro-5 peer wall).astro→^7.xinapps/docs/package.json— skipping^6entirely since Starlight went straight to^7.0.2.- Drop
@astrojs/tailwindand@astrojs/starlight-tailwind@^3from dependencies. Switchastro.config.mjsto the Vite@tailwindcss/viteplugin and bump@astrojs/starlight-tailwindto^5.0.0. Tailwind v3 → v4 config migration lands here (tailwind.config.ts→ CSS-first). - Transitive risk unchanged from original ticket: Vite
^6 → ^7, Zod^3 → ^4viaastro:content, deferred rendering / chunked collection-storage options (both new in Astro 7). - Validate:
bun --cwd apps/docs run typecheck && bun --cwd apps/docs run build; spot-check Starlight nav,pagefindsearch,astro-expressive-codeblocks, dark theme. wrangler pages deploy previewon a branch deploy before landing.
Recommend un-labeling
blockedand picking this up — it's real work but no longer waiting on anyone upstream.Related: #122 is a fresh dependabot bump (5.18.2 → 7.1.3) that hit the same wall; suggest closing that PR with
·@·d·ependabot i·gnore t·his major version(same treatment as #110) and doing the migration as one deliberate PR against this tracker instead.
Generated by Claude Code
- added a commit that references this issue
on Aug 13, 2026 Audit note (scheduled routine): dropping the
blockedlabel to match ground truth. Three prior audit passes (2026-07-12, 2026-07-19, 2026-07-23) all confirmed the same thing —@astrojs/starlight@0.41.4peer-depsastro: ^7.0.2, so the "no Starlight release supports Astro 6/7 yet" wall the ticket originally described is gone. The refreshed migration shape in the 2026-07-23 comment above (Starlight^0.41.4+ Astro^7+ drop@astrojs/tailwindfor the Vite@tailwindcss/viteplugin path) is what should ship.Related state changes today so the tracker sees the same world I do:
.github/dependabot.ymllanded in 43a60dc (via chore(ci): add .github/dependabot.yml — stop recurring astro-major PR flood (closes #123) #124). The ignore rule forastrosemver-majors in/apps/docsnow points to this tracker inline, so the Dependabot recurrences (chore(deps): bump astro from 5.18.1 to 6.1.8 in /apps/docs in the npm_and_yarn group across 1 directory #110/chore(deps): bump astro from 5.18.1 to 6.3.2 in /apps/docs in the npm_and_yarn group across 1 directory #116/chore(deps): bump the npm_and_yarn group across 2 directories with 2 updates #119/chore(deps): bump astro from 5.18.2 to 6.4.8 in /apps/docs in the npm_and_yarn group across 1 directory #121/chore(deps): bump astro from 5.18.2 to 7.1.3 in /apps/docs in the npm_and_yarn group across 1 directory #122) are suppressed until this closes.- Recommend re-titling to
docs: Astro 7 upgrade tracker (apps/docs)when someone picks it up so the ticket description and the label stop disagreeing.
Not filing a PR from the audit — this is a coordinated multi-package migration that deserves a deliberate branch, not a scheduled-routine drive-by.
Generated by Claude Code
Status audit — 2026-08-15
The 2026-08-13 Dependabot cycle filed six PRs that all belong to this migration:
PR Package Bump #126 @astrojs/starlight0.33.2 → 0.41.7 (needs astro: ^7)#128 zod(/apps/docs)3.25.76 → 4.4.3 (comes via astro:contenton v7)#130 @astrojs/starlight-tailwind(/apps/docs)3.0.1 → 5.0.0 (needs Tailwind v4 + @tailwindcss/vite)#131 @astrojs/starlight-tailwind(root)3.0.1 → 5.0.0 #133 @astrojs/react4.4.2 → 6.0.2 #134 tailwindcss3.4.19 → 4.3.3 None can land in isolation — Starlight 0.41.x peer-deps
astro: ^7,@astrojs/starlight-tailwind@^5requires Tailwind v4, and Astro 7 bringszod@^4transitively. They should be closed as part of this migration (or auto-close as their base branch rebases when the coordinated PR lands).PR #137 — draft, now ready for review — expands the
/apps/docsignore:block in.github/dependabot.ymlto cover the six peers above, so the next Dependabot cycle stops recreating them. That's a config-only unblocker (CI green: Constitution / Lint / Bundle Size / Type Check / Test / verify), not a substitute for the actual migration work still tracked here.Sibling trackers just filed for the other 2026-08-13 majors that don't belong here:
- chore(deps): TypeScript 7 upgrade tracker — workspace-wide migration from v5.9 #138 — TypeScript 5.9 → 7 (Dependabot chore(deps-dev): bump typescript from 5.9.3 to 7.0.2 #135 fails Type Check + verify on the raw bump)
- chore(deps): @cloudflare/workers-types 5 upgrade tracker — workspace-wide migration from v4 #139 —
@cloudflare/workers-types4 → 5 (Dependabot chore(deps-dev): bump @cloudflare/workers-types from 4.20260417.1 to 5.20260810.1 #127, touches 7 workspace files)
Filing separately per first-principles rule — silencing them under this tracker would hide real work that isn't part of the Astro migration.
Generated by Claude Code
- added a commit that references this issue
on Aug 15, 2026 - changed the title
[-]docs: Astro 6 upgrade tracker (apps/docs) — blocked on Starlight[/-][+]docs: Astro 5 → 7 upgrade tracker (apps/docs)[/+]on Sep 10, 2026 - added a commit that references this issue
on Sep 29, 2026
Context
Dependabot opened #110 to bump
astro5.18.1 → 6.1.8inapps/docs. CI has been red since 2026-04-21 because the upgrade can't be done as a drive-by — it's a real migration. This issue captures the work so the dependency PR can be closed without losing the intent.Blockers
From
bun.lock:@astrojs/starlight@0.33.2peer-depsastro: ^5.1.5→ no Starlight release supports Astro 6 yet. This is the gating blocker.@astrojs/tailwind@6.0.2peer-depsastro: ^3 || ^4 || ^5. The package itself is being deprecated upstream in favor of the Vite Tailwind v4 plugin path.Migration shape (when Starlight ships v6 support)
@astrojs/starlightto whatever release first declaresastro: ^6.astroitself inapps/docs/package.json.@astrojs/tailwindfrom dependencies; switchastro.config.mjsto the Vite@tailwindcss/viteplugin (Tailwind v4 path) — confirm@astrojs/starlight-tailwind@3.0.xstill works against the new wiring or wait for a Starlight Tailwind release that targets v4.bun --cwd apps/docs run typecheck && bun --cwd apps/docs run build. Spot-check Starlight nav, search (pagefind), code blocks (astro-expressive-code), and the dark theme.wrangler pages deploy previewon a branch deploy before landing.Risk areas
tailwind.config.ts→ CSS-first config).zodjump from v3 to v4 transitively via Astro 6 — content collections that importzfromastro:contentmay shift behavior.vite ^6 → ^7inside Astro — any custom Vite plugins inastro.config.mjs(currently none, but verify) need a compatibility check.Acceptance
apps/docsbuilds and deploys againstastro@^6.@astrojs/tailwinddependency.Refs
@dependabot ignore this major versionuntil this issue is actionable.