Skip to content

feat: migrate to Nuxt Content v4 (native API) - #137

Draft
atinux wants to merge 16 commits into
mainfrom
content-v4
Draft

atinux wants to merge 16 commits into
mainfrom
content-v4

Conversation

@atinux

@atinux atinux commented Oct 23, 2026 •

Copy link
Copy Markdown
Owner

Written by an AI agent (Amp) on behalf of @atinux, who hasn't reviewed it yet.

Migrates content-wind to the upcoming Nuxt Content v4 (nuxt/content-v4-temp), built on comark-content, using its native API instead of the v3 compatibility layer.

Changes

  • @nuxt/content now points to the @nuxt/content4 build of the v4 branch from pkg.pr.new (a2347b6). It isn't on npm yet. It includes nuxt/content-v4-temp#35 (headings link to themselves again, as v3 did, through comark 0.9.0's heading-links), nuxt/content-v4-temp#36 (content snapshots load in serverless functions, without which every page was a 404 on Vercel), nuxt/content-v4-temp#21 (no SQLite WASM chunk without v3 composables), nuxt/content-v4-temp#26 (fixes production hydration), nuxt/content-v4-temp#30 (rel="nofollow" on external links, like v3) and nuxt/content-v4-temp#40 (<ContentRenderer> renamed to <ContentDocument>).
  • Adds shiki, which v4 no longer bundles. The existing content.build.markdown.highlight config keeps working.
  • Removes content.config.ts and sets content.v3Composables: false. Without a config, v4 serves content/ as a single source.
  • Fetches pages with content.get(route.path) and navigation with content.navigation(), and renders pages with <ContentDocument>. With v3Composables: false, the deprecated <ContentRenderer> alias isn't registered: on a2347b6 it leaves the page body empty. Layouts come from page.data.layout.
  • Page meta no longer relies on page.seo: useSeoMeta() reads title, description and image straight from frontmatter. Every page now sets title and description in frontmatter, and About's seo.* fields move to the top level. image is now actually used as og:image. The "Pages" docs on the home page show the frontmatter instead of the v3 heading/paragraph rule.
  • content.get() needs no type argument, because v4 generates the page data types from the frontmatter.
  • v3Composables: false is still needed: the module defaults it to true, even without a content.config.ts.
  • Sets content.mode: 'server-only': the client fetches documents from the server instead of downloading the whole content snapshot. On Vercel, the function answers /__nuxt_content from its bundled snapshot. With nuxi generate, no /__nuxt_content files are emitted and client-side navigation uses the prerendered page payloads.
  • Drops experimental.sqliteConnector, which isn't a v4 option.
  • Imports LayoutKey from #app, which fixes the 3 vue-tsc errors that also exist on main.
  • Breaking: renames socials.twitter to socials.x in app.config.ts. Forks that set socials.twitter lose the X icon until they rename the key. The socials docs now list x and bluesky.

Checked against main (v3)

  • nuxi dev: / and /about render the same: layouts (full-width on About), MDC components (ButtonLink, :icon), navigation, and dual-theme code highlighting.
  • <title> and meta description match main on both pages (Content Wind and About).
  • nuxi generate from a fresh worktree with pnpm install --frozen-lockfile: prerenders all routes, with no SQLite or WASM files emitted. _nuxt is 892 KB (v3: 2.3 MB).
  • The static output hydrates: navigation is client-side (a window marker survives the clicks), and the navbar icons and color-mode toggle render.
  • pnpm lint passes, and vue-tsc reports 0 errors.

Known gaps (do not merge yet)

  • v4 is a preview build.

Use the @nuxt/content4 build from nuxt/content-v4-temp (pkg.pr.new),
aliased as @nuxt/content, and add shiki which v4 no longer bundles.

Amp-Thread-ID: https://ampcode.com/threads/T-01a16a15-f311-73fe-b4a0-cf59e174c951
Co-authored-by: Sébastien Chopin <atinux@gmail.com>
@vercel

vercel Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
content-wind Ready Ready Preview Nov 9, 2026 12:12pm UTC

Request Review

Drop the v3 compatibility layer: remove content.config.ts, disable
v3Composables, and read pages and navigation through the content client.
Page meta now comes from top-level frontmatter (title, description, image),
falling back to the leading heading and paragraph like v3 did.

Amp-Thread-ID: https://ampcode.com/threads/T-01a16a15-f311-73fe-b4a0-cf59e174c951
@atinux atinux changed the title chore: try Nuxt Content v4 preview feat: migrate to Nuxt Content v4 (native API) Oct 26, 2026
Drop the heading/paragraph fallback: content-v4 generates the page data
types from frontmatter, so content.get() needs no explicit type either.

Amp-Thread-ID: https://ampcode.com/threads/T-01a16a15-f311-73fe-b4a0-cf59e174c951
Picks up the production hydration fix (nuxt/content-v4-temp#26) and drops
the SQLite WASM chunk when v3 composables are disabled (nuxt/content-v4-temp#21).

Amp-Thread-ID: https://ampcode.com/threads/T-01a16a15-f311-73fe-b4a0-cf59e174c951
BREAKING CHANGE: forks that set socials.twitter in app.config.ts must rename the key to socials.x to keep the X icon in the navbar.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1a18b-8326-72de-9960-d4bc57501905
The preview depends on a pkg.pr.new build of comark while @comark/vue still pulls comark 0.8.1, and the two copies break the Nitro server build on Vercel. Override comark until it's released.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1a18b-8326-72de-9960-d4bc57501905
The previous preview couldn't load content snapshots in a serverless function (`useStorage is not defined`), so every page on Vercel was a 404. nuxt/content-v4-temp#36 fixes it, and #35 is now stacked on it.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1a18b-8326-72de-9960-d4bc57501905
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Bundle size

Explore the comparison →

Client 93.7 kB $\color{green}\textsf{(-71.0 kB, -43.1}\%\textsf{)}$ · Server 1.82 MB $\color{green}\textsf{(-37.3 kB, -2.0}\%\textsf{)}$

Initial page load PR Δ
/:slug(.) 95.1 kB −9.41 kB (−9.0%)
Largest changes in the client
Package or file Base PR Δ
node_modules/@sqlite.org/sqlite-wasm 54.8 kB n/a −54.8 kB (−100.0%)
node_modules/property-information 5.18 kB n/a −5.18 kB (−100.0%)
node_modules/@nuxtjs/mdc 4.93 kB n/a −4.93 kB (−100.0%)
[unassigned] 9.11 kB 4.47 kB −4.64 kB (−50.9%)
node_modules/@nuxt/content 3.56 kB n/a −3.56 kB (−100.0%)
node_modules/comark-content n/a 1.35 kB +1.35 kB
node_modules/@comark/vue n/a 1.27 kB +1.27 kB
node_modules/comark n/a 1.25 kB +1.25 kB
node_modules/@nuxt/content4 n/a 668 B +668 B
node_modules/nuxt 18.8 kB 18.2 kB −602 B (−3.2%)

And 44 more packages or files.

Largest changes in the server
Package or file Base PR Δ
[unassigned] 1.76 MB 1.75 MB −18.2 kB (−1.0%)
node_modules/@nuxt/content 8.06 kB n/a −8.06 kB (−100.0%)
node_modules/@nuxtjs/mdc 6.51 kB n/a −6.51 kB (−100.0%)
content/database.compressed.mjs 4.76 kB n/a −4.76 kB (−100.0%)
node_modules/@nuxt/content4 n/a 2.48 kB +2.48 kB
node_modules/@comark/vue n/a 1.91 kB +1.91 kB
.nuxt/dist/server/client.precomputed.mjs 2.43 kB 997 B −1.44 kB (−59.0%)
node_modules/db0 562 B n/a −562 B (−100.0%)
node_modules/nuxt 24.3 kB 23.9 kB −449 B (−1.8%)
node_modules/nitropack 10.0 kB 9.62 kB −397 B (−4.0%)

And 52 more packages or files.

Brotli sizes. Initial page load counts the JavaScript and CSS a route loads before it renders. Measured by nuxt-bundle-analyzer for b73ca97.

atinux and others added 5 commits November 7, 2026 09:47
Pins @nuxt/content to the pkg.pr.new preview of nuxt/content-v4-temp#35 at 9476cb5, rebased on v4 (comark ^0.9.0) with the serverless fix. comark 0.9.0 ships the heading-links plugin, so the comark override is no longer needed: a single comark@0.9.0 resolves.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1b55b-d6d9-77b9-8247-e18ca613421e
Co-authored-by: Amp <amp@ampcode.com>
Pins @nuxt/content to the pkg.pr.new preview of nuxt/content-v4-temp#35 at 60b0921, on the latest v4 (which now includes #36). Same code as 9476cb5.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1b55b-d6d9-77b9-8247-e18ca613421e
Co-authored-by: Amp <amp@ampcode.com>
The client fetches documents from the server instead of downloading the whole content snapshot. Static hosting still works: prerendered pages navigate through their payloads.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1a18b-8326-72de-9960-d4bc57501905

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants