perf: speed up utoopack markdown and demo HMR

[fireairforce]

Summary

• share Markdown transform results across isolated Utoopack loader workers with dependency-aware, session-scoped locking
• split external demo data into a stable aggregate runtime plus one lightweight aggregate overlay per Markdown document
• hot-update demo source, sidecar descriptions/styles, metadata, and import-graph changes without replacing the whole page module
• deep-merge runtime assets safely, including explicit deletion semantics for deferred metadata and previewer props
• scope the Utoopack engine defaults only to tech stacks that opt into deferred sidecars: disable background cache snapshots and memory eviction that contend with small HMR updates
• preserve full-page invalidation for structural Markdown/frontmatter changes and preserve legacy production, non-Utoopack, inline-demo, and custom-renderer paths

Related engine work:

• Utoopack delivery, persistence, and timing: perf(pack): accelerate large-graph HMR updates utooland/utoo#3241
• Turbopack dynamic HMR chunk lists: perf(turbopack): add opt-in dynamic HMR chunk lists utooland/next.js#169

Root causes

Ant Design has a large eager documentation graph. The same Markdown/demo analysis was repeated across isolated loader workers, demo-sidecar data was embedded into the page module, and a background persistent-cache snapshot could serialize about 138k tasks while a tiny Markdown update waited. Replacing demo modules could also leave stale deleted-module references when a page and independent preview subscribed together.

This PR keeps the page shell stable, moves deferred demo data into a self-accepted overlay, and asks Utoopack to avoid background snapshot/eviction work only for that scoped mode.

Results

• repeated Markdown transform benchmark: about 25.4s to 7.55s
• Ant Design one-page first Markdown edit with background snapshots disabled: about 225ms to DOM update
• warm page plus independent-demo edits: about 0.1 to 0.7s
• entry HMR list with the related Utoopack change: 4,628 chunks to 2 direct chunks; loaded dynamic groups own their lists
• no full reload or deleted-module error for normal preview, independent demo, iframe/off-route, source edit, import add/remove, and sidecar metadata deletion checks

A cold restart with two routes reconnecting and materializing simultaneously can still take about 45s; that is a remaining on-demand route/materialization problem rather than the background snapshot or ordinary Markdown-update path fixed here.

Safety

• scoped demo HMR is development-only and capability-gated by deferDemoSidecar
• user-specified Utoopack persistence or eviction options override dumi defaults
• structural frontmatter/page changes keep the conservative full-page path
• runtime and overlay use canonical module identity plus separate semantic channels
• removed title/description/keywords/snapshot and deferred jsx/description/style values explicitly clear old runtime values
• overlay metadata runs the tech-stack generateMetadata hook; third-party hooks should remain pure and compatible with an entry-local overlay asset
• first config resolution and file generation reuse the same registered tech-stack instances

Validation

dumi

• npm test: 207 passed, 12 skipped
• npm run lint:es: passed
• npm run build: Father ESM/CJS/declarations and Rust WASM passed
• git diff --check: passed

Ant Design

• full production site build passed, including SSR, client build, page pre-rendering, and 2,659 emitted assets
• real-browser HMR covered ordinary pages and independent demo pages together

Utoopack/Turbopack

• 73/73 pack tests and 6/6 pack-shared tests passed
• CJS/ESM build, typechecks, Biome, cargo check -p pack-core, and the targeted dynamic HMR snapshot/runtime assertion passed

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
dumi	Ready	Preview, Comment	Jul 20, 2026 5:15pm

[pkg-pr-new]

More templates

• @examples/mobile
• @examples/normal
• @examples/vue

dumi

npm i https://pkg.pr.new/umijs/dumi@2366

dumi-assets-types

npm i https://pkg.pr.new/umijs/dumi/dumi-assets-types@2366

@dumijs/vue-meta

npm i https://pkg.pr.new/umijs/dumi/@dumijs/vue-meta@2366

father-plugin-dumi-theme

npm i https://pkg.pr.new/umijs/dumi/father-plugin-dumi-theme@2366

@dumijs/preset-vue

npm i https://pkg.pr.new/umijs/dumi/@dumijs/preset-vue@2366

dumi-theme-mobile

npm i https://pkg.pr.new/umijs/dumi/dumi-theme-mobile@2366

commit: e10ae6c