fix: reduce minimal bundle size

[harlan-zw]

Linked issue

No linked issue.

Type of change

• Documentation
• Bug fix
• Enhancement
• New feature
• Chore
• Breaking change

Description

Reduces the core and Vue bundle benchmarks with small runtime rewrites that preserve the existing public API surface. The Vue server benchmark stays on the existing import shape: useHead from @unhead/vue and SSR utilities from @unhead/vue/server.

Bundle size report from CI, baseline main @ 0cdf3224:

• Core client minimal: 5.1 kB gz, unchanged within report threshold
• Core client full: 8.5 kB -> 8.5 kB gz (-36 B)
• Core server minimal: 4.6 kB -> 4.5 kB gz (-29 B)
• Vue client minimal: 5.7 kB -> 5.6 kB gz (-37 B)
• Vue client full: 9.3 kB -> 9.2 kB gz (-62 B)
• Vue server minimal: 5.0 kB -> 5.0 kB gz (-31 B)

Verification

• pnpm lint
• pnpm typecheck
• pnpm build
• pnpm test:bundle-size && pnpm test:vue-bundle-size
• pnpm vitest run

[github-actions]

📦 Bundle Size

🟢 8 smaller · net -0.3 kB gz

Bundle	Gzipped	Δ
Client (Full)	8.5 kB → 8.5 kB	🟢 -36 B (-0.4%)
Server (Minimal)	4.6 kB → 4.5 kB	🟢 -29 B (-0.6%)
Vue Client (Minimal)	5.7 kB → 5.6 kB	🟢 -37 B (-0.6%)
Vue Client (Full)	9.3 kB → 9.2 kB	🟢 -62 B (-0.7%)
Vue Server (Minimal)	5 kB → 5 kB	🟢 -31 B (-0.6%)
React Client (Full)	9.4 kB → 9.4 kB	🟢 -52 B (-0.5%)
React Server (Minimal)	4.8 kB → 4.8 kB	🟢 -28 B (-0.6%)
Schema.org (Minimal)	9.6 kB → 9.6 kB	🟢 -21 B (-0.2%)

All bundles (12)

Bundle	Gzipped	Raw
Core
Client (Minimal)	5.1 kB	12.8 kB	✅
Client (Full)	8.5 kB	22 kB	🟢
Server (Minimal)	4.5 kB	11.3 kB	🟢
Vue
Vue Client (Minimal)	5.6 kB	13.8 kB	🟢
Vue Client (Full)	9.2 kB	23.9 kB	🟢
Vue Server (Minimal)	5 kB	12.3 kB	🟢
React
React Client (Minimal)	5.6 kB	13.8 kB	✅
React Client (Full)	9.4 kB	24.4 kB	🟢
React Server (Minimal)	4.8 kB	12 kB	🟢
Schema.org
Schema.org (Minimal)	9.6 kB	26.4 kB	🟢
Schema.org Imports	0.1 kB	0.1 kB	✅
Schema.org Vue Meta	0.4 kB	0.8 kB	✅

---

⚡ Performance (directional)

⚠️ 1 slower · past the per-metric noise gate

Benchmark	base → PR	Δ
SSR allocated / render	267.8 KiB → 273.7 KiB	🔴 +5.8 KiB (+2.2%)

All benchmarks (9)

Benchmark	PR	Δ	RME
SSR render (CPU)	0.425 ms	~ noise	±11.2%
SSR render (wall)	0.282 ms	~ noise	±5.7%
SSR allocated / render	273.7 KiB	🔴 +5.8 KiB (+2.2%)	—
Schema.org cached render (CPU)	0.384 ms	~ noise	±5.5%
Schema.org cached render (wall)	0.254 ms	~ noise	±1.9%
Schema.org cached allocated / render	145.2 KiB	~ noise	—
CSR DOM mutations / nav	38	~ noise	—
CSR re-render (CPU)	0.834 ms	~ noise	±4.8%
CSR re-render (wall)	0.478 ms	~ noise	±1.9%

_{Baseline: main @ 0cdf322 · 2026-06-30 · gzipped is the headline size metric · perf is directional (shared-runner, gated)}

[coderabbitai]

📝 Walkthrough

Walkthrough

Refactors unhead's client DOM export surface, DOM renderer internals, script lifecycle handling, plugin purity annotations, and server-side tag weighting/prop stringification. Separately relocates Vue's injectHead into install.ts and updates Vue render scheduling.

Changes

Unhead Core Refactors

Layer / File(s)	Summary
Client renderDOMHead export cleanup packages/unhead/src/client/index.ts, packages/unhead/src/client/renderDOMHead.ts	Removes the deprecated local renderDOMHead wrapper, re-exporting createDomRenderer and renderDOMHead directly, and adds a deprecation JSDoc note to renderDOMHead.
DOM render state and defaultView handling packages/unhead/src/client/renderDOMHead.ts	Updates cleanup and state reuse logic, reorders defaultView/document handling, and switches event dispatch, title updates, and element/fragment creation to use dom APIs.
Plugin purity annotations packages/unhead/src/plugins/aliasSorting.ts, packages/unhead/src/plugins/safe.ts	Adds or corrects /* @PURE */ annotations on defineHeadPlugin calls.
Script lifecycle and registry refactor packages/unhead/src/scripts/useScript.ts, packages/unhead/test/unit/scripts/events.test.ts	Changes script id derivation, event binding, terminal-state handling, warmup checks, and registry insertion, and adds a test for prototype-collision script ids.
Server-side tag weighting and prop stringification packages/unhead/src/server/sort.ts, packages/unhead/src/server/util/propsToString.ts	Replaces weight lookup objects and regex constants with inline conditionals, and inlines class/style stringification logic.

Vue injectHead Relocation and Debounce Fix

Layer / File(s)	Summary
injectHead relocated to install.ts packages/vue/src/install.ts, packages/vue/src/composables.ts, packages/vue/src/scripts/useScript.ts	Adds injectHead() to install.ts, re-exports it from composables.ts, and updates useScript.ts to import it from install.ts.
Debounced renderer race fix packages/vue/src/client.ts	Replaces createDebouncedFn with a local debouncedRenderer that guards scheduled renders with a renderId counter.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• unjs/unhead#787: Both PRs modify packages/unhead/src/client/renderDOMHead.ts, including DOM/document handling and renderer state behavior.
• unjs/unhead#807: Both PRs modify packages/unhead/src/scripts/useScript.ts, including script lifecycle and registry behavior.

Poem

A rabbit hopped through code so bright,
Trimmed the paths and set them right.
Head and script now bound with care,
New renders hop on only the latest stair,
And dom now leads the moonlit way —
Hop, hop, hooray for a tidier day! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately reflects the bundle-size reduction focus of the PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description matches the template and includes linked issue, change type, detailed description, and verification steps.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/reduce-minimal-bundle-size

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/unhead/src/scripts/useScript.ts`:
- Around line 27-28: The script registry lookup in useScript is vulnerable
because head._scripts is a normal object and id is user-controlled, so keys like
constructor or __proto__ can hit inherited properties or affect the prototype.
Update the script-id registry used by useScript and any related
initialization/access in head._scripts to use a null-prototype structure, and
keep the bracket lookup against that safe registry so ids only resolve to own
entries.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 89cc2fa9-6117-4e7e-a99c-552bbe3e3d87

📥 Commits

Reviewing files that changed from the base of the PR and between 0cdf322 and dae110b.

📒 Files selected for processing (11)

• packages/unhead/src/client/index.ts
• packages/unhead/src/client/renderDOMHead.ts
• packages/unhead/src/plugins/aliasSorting.ts
• packages/unhead/src/plugins/safe.ts
• packages/unhead/src/scripts/useScript.ts
• packages/unhead/src/server/sort.ts
• packages/unhead/src/server/util/propsToString.ts
• packages/vue/src/client.ts
• packages/vue/src/composables.ts
• packages/vue/src/install.ts
• packages/vue/src/scripts/useScript.ts