Astro 6, Shiki 4, and Major Dependency Upgrade with Dead Code Cleanup

Summary

Upgraded the site from Astro 5.16.11 to Astro 6.1.2 -- a major framework version jump that brings Vite 7, Zod 4, and Shiki 4 under the hood. Updated 27 packages total (11 major, 16 minor/patch). Discovered and removed rehype-mermaid and playwright as dead code, shedding 181 packages from the dependency tree.

Why Care

Astro 6 is the first major Astro release since the Content Layer API was introduced in Astro 5. It drops legacy content collection support entirely, upgrades the build pipeline to Vite 7, and introduces new capabilities like built-in fonts, live content collections, and CSP. Staying current keeps us on supported versions and unblocks future features.
The dead code cleanup is equally significant -- we were carrying Playwright (a full headless browser) as a dependency for rehype-mermaid, which never actually processed any Mermaid blocks. Our custom pipeline in AstroMarkdown.astro intercepts them before rehype runs, and MermaidChart.astro renders them client-side via the Mermaid CDN.

Implementation

Major Version Bumps

PackagePreviousUpdatedNotes
astro5.16.116.1.2Vite 7, Zod 4, Shiki 4 bundled
@astrojs/mdx4.3.135.0.3Astro 6 compatibility
@astrojs/node9.5.210.0.4Astro 6 compatibility
@astrojs/prism3.3.04.0.1Astro 6 compatibility
@astrojs/svelte7.2.58.0.4Astro 6 compatibility
@astrojs/vercel9.0.410.0.3Astro 6 compatibility
shiki3.15.04.0.2Cleanup release, our APIs already compatible
glob11.0.313.0.6CLI moved to separate package (we only use JS API)
tailwind-variants2.1.03.2.2
uuid11.1.013.0.0
@vercel/routing-utils5.3.06.1.1

Minor/Patch Bumps

PackagePreviousUpdated
svelte5.43.145.55.1
tailwindcss4.1.174.2.2
@tailwindcss/vite4.1.174.2.2
@tailwindcss/forms0.5.100.5.11
@iconify-json/tabler1.2.231.2.33
@tabler/icons3.35.03.41.1
choices.js11.1.011.2.1
undici7.16.07.24.6
smol-toml1.6.01.6.1
mdast-util-from-markdown2.0.22.0.3
mdast-util-to-hast13.2.013.2.1
unist-util-visit5.0.05.1.0
dotenv17.2.317.3.1
serve14.2.514.2.6
tsx4.20.64.21.0
@astrojs/check0.9.60.9.8
@astrojs/sitemap3.7.03.7.2

Content Collection Migration (Astro 6 / Zod 4)

Astro 6 removes all legacy content collection support. Two collections needed migration:
src/content.config.ts:
  • Changed import { defineCollection, z } from 'astro:content' to separate imports: defineCollection from astro:content, z from astro/zod (Zod 4 requirement)
  • Migrated cardCollection from type: 'data' to loader: glob({pattern: "**/*.json", base: "./src/content/cards"})
  • Migrated reportCollection from type: 'content' to loader: glob({pattern: "**/*.md", base: "./src/content/reports"})
src/content/cards/config.ts:
  • Updated z import to use astro/zod (legacy file, superseded by src/content.config.ts)

Dead Code Removal (-181 packages)

rehype-mermaid + Playwright

Removed rehype-mermaid from astro.config.mjs. Analysis of the full rendering chain confirmed it never processed Mermaid code blocks:
  1. AstroMarkdown.astro detects lang="mermaid" via getLanguageRoutingStrategy() from shikiHighlighter.ts
  2. Routes them to MermaidChart.astro component
  3. MermaidChart.astro loads Mermaid client-side from CDN (https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs)
  4. Browser renders SVGs at runtime
Since rehype-mermaid was the only consumer of playwright, both were removed along with:
  • decktape (slide-to-PDF export, also depended on Puppeteer)
  • The postinstall script that installed Playwright Chromium browsers

imagekit

The imagekit npm package (v6.0.0, deprecated) was never imported in any source file. The site uses ImageKit CDN URLs (ik.imagekit.io) directly in templates, which are independent of the npm package.

Not Upgraded

  • TypeScript: stays at 5.9.3. The Astro toolchain (tsconfck, @astrojs/check, svelte2tsx) all require TypeScript 5.x via peer dependencies. Will revisit when the ecosystem catches up to TS 6.

Known Impact

  • pnpm export-pdf is temporarily broken -- decktape was removed. The script at scripts/export-slides-to-pdf.js still exists but needs an alternative PDF export approach.
  • Markdown heading ID generation algorithm changed in Astro 6 -- existing anchor links may break on the deployed site.

Files Changed

text 
Modified:
  astro.config.mjs (removed rehype-mermaid import and plugin config)
  package.json (27 upgrades, 4 removals, postinstall removed)
  pnpm-lock.yaml
  src/content.config.ts (Zod 4 import, legacy collection migration)
  src/content/cards/config.ts (Zod 4 import)

Build Verification

  • Production build completes successfully (~101 seconds)
  • Dev server starts clean (2.7 seconds, no errors)
  • All static pages generated
  • Vercel adapter bundles correctly
  • Sitemap generated