feat: migrate to Astro 6 + Content Layer API#28
Open
nathanredblur wants to merge 3 commits into
Open
Conversation
Upgrade astro 5.17.1 -> 6.2.1 via @astrojs/upgrade. Brings @astrojs/cloudflare 12 -> 13.3, @astrojs/svelte 7 -> 8.1, plus Vite 7 / Zod 4 / Shiki 4. Astro 6 removes the legacy content collections API. The legacy.collectionsBackwardsCompat flag doesn't preserve entry.render() at runtime in 6.2.1, so migrate collections to the Content Layer API: - src/content/config.ts -> src/content.config.ts using glob() loader from astro/loaders; generateId strips /index so slugs match the legacy filesystem-based ids - Replace entry.slug with entry.id across content-utils, rss.xml, [...slug], PostCard, PostPage, ArchivePanel - Replace entry.render() with render(entry) imported from astro:content - Resolve cover image basePath from entry.filePath instead of getDir(entry.id) (id no longer contains the file path) Cloudflare adapter v13 breaking changes: - wrangler.jsonc main -> "@astrojs/cloudflare/entrypoints/server" - Static output moved to dist/client/, so pagefind --site dist/client Bump wrangler 4.62 -> 4.87 to satisfy @cloudflare/vite-plugin peer. Known issue: astro dev currently returns 500 "module is not defined" from the @cloudflare/vite-plugin runner-worker. Production build and wrangler dev on the built output both work; local dev via `pnpm wrangler dev` is the workaround until the dev runner is fixed.
astro dev 500s on every request with "module is not defined" when the @cloudflare/vite-plugin runner loads a component whose dep graph includes the CJS `debug` package: it references `module.exports`, and `module` is not a global in the workerd runner. Astro core already replaced `debug` with `obug` (ESM fork) in withastro/astro#15565, but integrations like expressive-code still pull `debug` via their markdown/rehype pipelines (expressive-code/expressive-code#439 tracks the same error). `obug` only exposes named exports, so a raw alias breaks consumers that do `import debug from "debug"`. Add `src/shims/debug.js` which re-exports obug and re-exposes a default, then wire it in via vite.resolve.alias. Install obug as a direct dependency so the shim resolves in the Workers runner (it's only a transitive dep of astro otherwise). Also add .wrangler to .gitignore - the new dev mode writes local state there. Verified: all routes (/, /blog/, /posts/..., /about/, /archive/, /projects/) return 200 under pnpm dev; pnpm check and pnpm build stay green.
Add TODO pointers next to both the astro.config.mjs alias and src/shims/debug.js so the workaround is easy to retire once withastro/astro#16569 ships in a @astrojs/cloudflare release.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrates the site from Astro 5.17.1 → 6.2.1 following the official upgrade guide.
Ran
pnpm dlx @astrojs/upgradeand followed the breaking changes through: bumped@astrojs/cloudflare12 → 13.3,@astrojs/svelte7 → 8.1,wrangler4.62 → 4.87, plus the Vite 7 / Zod 4 / Shiki 4 transitive upgrades.Content collections — migrated to Content Layer API
Astro 6 removes the legacy content collections API. The
legacy.collectionsBackwardsCompatflag is advertised as a migration helper, but in 6.2.1 it does not preserveentry.render()at runtime (build still fails withTypeError: entry.render is not a function), so the legacy-first / migrate-later plan wasn't viable. Done in this PR:src/content/config.ts→src/content.config.tsusingglob()loader fromastro/loaders.generateIdstrips/indexso slugs likeguide/keep matching the oldentry.slugentry.slug→entry.idacrosscontent-utils,[...slug],rss.xml,PostCard,PostPage,ArchivePanelentry.render()→render(entry)fromastro:contentbasePathresolves fromentry.filePathinstead ofgetDir(entry.id)(the id no longer contains the file path)znow imported fromastro/zod(astro:content export is deprecated)Cloudflare adapter v13 breaking changes
wrangler.jsonc:mainfield →"@astrojs/cloudflare/entrypoints/server"(v13 deletes the old_worker.js/index.jspath)dist/client/, sopagefind --site dist→pagefind --site dist/clientin the build script.wrangler/added to.gitignore(new dev mode writes local state there)Dev workaround:
debugpackage crashes workerd runnerastro devreturned HTTP 500 on every request withReferenceError: module is not defined— the CJSdebugpackage is pulled transitively bymicromarkandstylus, and@cloudflare/vite-plugin's workerd runner has nomoduleglobal. Worked around here by aliasingdebugto an ESM shim backed byobug(same replacement astro core uses after withastro/astro#15565).Upstream fix proposed in withastro/astro#16569 — applies the same alias inside
@astrojs/cloudflareso nobody needs the local workaround anymore. Once that ships in a@astrojs/cloudflarerelease, remove:src/shims/debug.jsdebugalias inastro.config.mjsobugdep frompackage.jsonBoth locations carry a
TODOpointing at #16569.Test plan
pnpm check— 0 errors, 0 warningspnpm build— all 12 prerendered pages rendered with content, 3 resume PDFs generated, Pagefind indexes 6 pages / 1833 wordspnpm dev—/,/posts/:slug/,/blog/,/about/,/archive/,/projects/all return 200 with full contentpnpm wrangler devagainst the built output — all routes 200 under the real Workers runtime