Skip to content

chore(docus): move to released 5.13.0 and drop the local patch - #210

Open
sisou wants to merge 5 commits into
mainfrom
chore/docus-5-13
Open

chore(docus): move to released 5.13.0 and drop the local patch#210
sisou wants to merge 5 commits into
mainfrom
chore/docus-5-13

Conversation

@sisou

@sisou sisou commented Sep 8, 2026

Copy link
Copy Markdown
Member

Replaces the pkg.pr.new preview pin and the local pnpm patch with docus@^5.13.0 from npm.

Why

21f0b37 pinned https://pkg.pr.new/docus@1304 — a CI build of nuxt-content/docus#1304, taken about an hour before that PR merged. 387d9b4 then re-added a 135-line patch on top. Both fixes have been released for months:

Fix Upstream Released
MCP tools derive page URLs from the request origin #1302 5.8.0
get-page fetches raw markdown via event.$fetch (absolute self-request 404s on Workers) #1304 5.8.0
Assistant's MCP client routed through event.fetch (CF Workers self-fetch error 1042) #1309 5.10.1

Verified against the published tarballs, not just changelogs. Upstream's version of the last one supersedes our patch — it moved to runtime/server/utils/assistant.ts in 5.12, so the patch can no longer apply anyway. The preview tarball is also an ephemeral CI artifact, and patchedDependencies only matched it because the build happened to carry version 5.7.0.

Two regressions the bump exposed

Code groups (78 of them) silently broke. docus 5.13 pulls @nuxt/ui 4.11, which removed useComponentUI in favour of useComponentProps. Separately, an app-level ProseCodeGroup override is now dropped from the bundle entirely — no build error, no chunk emitted, and <ProseCodeGroup> leaks into the rendered HTML. A verbatim copy of upstream's own component in app/components/ breaks identically, so this isn't specific to our fork. Moving it to app/components/global/ (globally registered, which is what MDC's resolveComponent needs) restores it.

pnpm typecheck failed inside docus itself, which CI runs:

docus/app/composables/useSeo.ts(37,53): error TS2339: Property 'schema'
does not exist on type '{ title?: string; description?: string; }'

5.13.0's JSON-LD feature (#1433) reads AppConfig['seo']['schema'], but only declares it in an augmentation that loses against the AppConfig Nuxt generates from resolved app.config values. Still unfixed on docus main. docus-seo.d.ts re-declares the shape on CustomAppConfig; drop it when upstream fixes this.

Verification

pnpm lint, pnpm typecheck and pnpm build all pass.

Compared against a baseline build of main in a separate worktree — identical: 108 pages, 144 code-group tabs, same tab labels and icons. The 11 prerender 500s (/protocol/validators/*, /protocol/storage/mempool, /protocol/consensus/block-format and others) occur on main too and are untouched by this PR.

Side effect worth a look in the preview

The og-image v6 upgrade (docus 5.9.0) prerenders OG images at build time: 101 static PNGs (3.4 MB) in public, and the satori/resvg wasm (2.48 MB) is gone from the Worker — server bundle drops 11 MB → 6.4 MB, which is useful headroom against Workers size limits. Also new: /.well-known/skills/* routes from docus's skills module, served from the existing skills/ dir.

Worth eyeballing on the preview: code groups, OG images, TOC (ContentToc default variant changed to circuit in 5.12), and the assistant panel (moved to Nuxt UI USidebar).

🤖 Generated with Claude Code

https://claude.ai/code/session_01TCgqQUpt4KBXi9U9ae5iq6

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 8, 2026

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
developer-center-dev-worker 116b580 Commit Preview URL

Branch Preview URL
Sep 08 2026, 03:45 PM

@sisou

sisou commented Sep 8, 2026

Copy link
Copy Markdown
Member Author

Filed the upstream fix: nuxt-content/docus#1437.

Root cause turned out to be broader than seo.schema: docus/app/types/index.d.ts is a module, so its declare module 'nuxt/schema' block is a module augmentation that only applies once something pulls the file into the program — nothing does in an app installing docus from npm, so every AppConfig field docus declares there is silently missing and falls back to the shapes generated from nuxt.schema.ts. It only became visible now because 5.13.0's useSeo reads a field that exists solely in that file.

The upstream fix is a one-liner in layer/index.d.ts. Once it ships, docus-seo.d.ts here can go.

sisou and others added 5 commits September 8, 2026 17:40
The pkg.pr.new pin was a build of nuxt-content/docus#1304, taken ~1h
before that PR merged. Both patched fixes are released now:

- #1302/#1304 (MCP tools: derive page URLs from the request origin, fetch
  raw markdown through event.$fetch so get-page works on Workers) shipped
  in 5.8.0
- #1309 (route the assistant's MCP client through event.fetch to avoid the
  CF Workers self-fetch 1042 error) shipped in 5.10.1, and upstream's
  version supersedes the local patch

So the patch file and the ephemeral CI tarball can both go.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TCgqQUpt4KBXi9U9ae5iq6
docus 5.13 pulls @nuxt/ui 4.11, which drops `useComponentUI` in favour of
`useComponentProps`. Two separate breakages came out of that bump:

- the composable import no longer resolves, failing `nuxi typecheck`
- an app-level `ProseCodeGroup` is dropped from the bundle entirely under
  the new stack — no build error, no chunk emitted, and `<ProseCodeGroup>`
  leaks into the rendered HTML on all 78 code groups. A verbatim copy of
  upstream's own component in `app/components/` breaks the same way, so
  this is not specific to our fork of it.

Moving the file to `app/components/global/` (registered globally by Nuxt,
which is what MDC's `resolveComponent('ProseCodeGroup')` needs) restores
it. Prerendered output again matches the previous build: 144 tabs across
108 pages, same labels and icons.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TCgqQUpt4KBXi9U9ae5iq6
docus 5.13 added a configurable JSON-LD identity schema (#1433). Its own
`useSeo` composable reads `AppConfig['seo']['schema']`, but the field is
only declared in an `AppConfig` augmentation that loses against the
`AppConfig` Nuxt generates from the resolved app.config values, so
`nuxi typecheck` fails inside the layer:

  docus/app/composables/useSeo.ts(37,53): error TS2339: Property 'schema'
  does not exist on type '{ title?: string; description?: string; }'

Still unfixed on docus main — `layer/nuxt.schema.ts` declares `seo` with
title and description only. Re-declaring the shape on `CustomAppConfig`,
which Nuxt does merge in, unblocks CI. Remove once upstream ships it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TCgqQUpt4KBXi9U9ae5iq6
Digging into it for the upstream report turned up the actual cause: the
field is declared in `docus/app/types/index.d.ts`, which is a module, so its
`declare module 'nuxt/schema'` block only applies once something pulls the
file into the program — and nothing does in an app installing docus from
npm. Comment only; the declaration is unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TCgqQUpt4KBXi9U9ae5iq6
Two visual changes the docus 5.13 bump brought in, both from dependencies
rather than from docus itself:

- @nuxt/ui 4.11 added `lg:ms-0` to the ContentToc root. That cancels the
  left bleed but keeps the 24px inline padding, so the links sat 24px into
  their own grid column and the column lost 24px of width (162.6px instead
  of 186.6px at 2560px wide). `lg:ps-0` restores it.
- docus renders `UContentSurround` on every docs page. It resolved to
  nothing on @nuxt/content 3.12, but 3.16 returns the neighbouring pages, so
  prev/next cards appeared at the bottom of every page. Hidden, since the
  site doesn't use them.

Measured against production on /mini-apps/: TOC content box now x=1773.9
w=186.6 in both, and the surround links are gone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TCgqQUpt4KBXi9U9ae5iq6
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.

1 participant