fix(vue): symmetric HeadStream vnodes for clean streaming hydration by harlan-zw · Pull Request #748 · unjs/unhead

harlan-zw · 2026-04-22T14:23:47Z

🔗 Linked issue

N/A

❓ Type of change

📚 Description

Streaming head updates were emitted as <script innerHTML="..."> vnodes on the server but as null on the client, producing vnode-type hydration mismatches in @unhead/vue's streaming mode.

HeadStream now emits a symmetric <script data-allow-mismatch="children"> on both server and client. Server fills innerHTML with the pending suspense-chunk payload (or empty before the shell renders); client renders an empty script. Matching vnode types + data-allow-mismatch let Vue's hydrator silence the inner-text diff cleanly.

Scope is intentionally narrow: only the HeadStream component and its tests change here. The related prepareStreamingTemplate outlet-split + example shell changes will follow in a separate PR.

✅ Test plan

pnpm -F @unhead/vue test (147 passed)
pnpm -C examples/vite-ssr-vue-streaming test — new Playwright regression guard asserts every window.__unhead__.push script carries data-allow-mismatch, and that at least one such script was injected (non-vacuous)

Summary by CodeRabbit

Bug Fixes
- Improved Vue SSR streaming hydration by ensuring proper script element matching between server and client, preventing hydration mismatches in streaming scenarios.
Tests
- Added regression test for hydration script validation.
- Updated streaming test cases to verify new placeholder behavior.

coderabbitai · 2026-04-22T14:24:03Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5bab8bd8-8b87-4aab-962d-6155412151ec

📥 Commits

Reviewing files that changed from the base of the PR and between 769eb10 and 7b3ead1.

📒 Files selected for processing (5)

examples/vite-ssr-vue-streaming/tests/streaming.spec.ts
packages/vue/src/stream/client.ts
packages/vue/src/stream/server.ts
packages/vue/src/stream/vite.ts
packages/vue/test/streaming.test.ts

✅ Files skipped from review due to trivial changes (2)

examples/vite-ssr-vue-streaming/tests/streaming.spec.ts
packages/vue/src/stream/vite.ts

🚧 Files skipped from review as they are similar to previous changes (2)

packages/vue/test/streaming.test.ts
packages/vue/src/stream/server.ts

📝 Walkthrough

Walkthrough

This PR modifies the HeadStream component to render a <script data-allow-mismatch="children"> placeholder on both server and client instead of returning null, enabling proper Vue SSR hydration during streaming. Tests and documentation are updated accordingly.

Changes

Cohort / File(s)	Summary
HeadStream Component Logic `packages/vue/src/stream/client.ts`, `packages/vue/src/stream/server.ts`	Changed `HeadStream` from returning `null` to rendering `<script data-allow-mismatch="children">` placeholder. Server unconditionally outputs the script with `innerHTML` containing pushed head updates; client renders matching script vnode for hydration alignment.
Streaming Tests `packages/vue/test/streaming.test.ts`	Updated assertions to verify `<script data-allow-mismatch="children">` output rather than null renders. Added test for pre-shell-render behavior and tightened XSS payload validation.
Plugin Documentation `packages/vue/src/stream/vite.ts`	Updated JSDoc comments to explain `<HeadStream />` injection behavior and `data-allow-mismatch` hydration tolerance semantics. No functional logic changes.
E2E Regression Test `examples/vite-ssr-vue-streaming/tests/streaming.spec.ts`	Added test verifying scripts containing `window.__unhead__.push` possess the `data-allow-mismatch` attribute.

Sequence Diagram

sequenceDiagram
    actor Browser
    participant Server
    participant HeadStream Client
    participant Vue Hydration

    Browser->>+Server: Request page
    Server->>Server: Render HeadStream component
    Server->>Server: Output `<script data-allow-mismatch="children">`...
    Server-->>-Browser: Send HTML (streaming)
    
    Note over Browser: HTML received with script placeholder
    
    Browser->>+HeadStream Client: Parse & mount
    HeadStream Client->>HeadStream Client: setup() returns script vnode
    HeadStream Client-->>-Browser: Render `<script data-allow-mismatch="children">`
    
    Note over Vue Hydration: Mismatch tolerant hydration
    Vue Hydration->>Vue Hydration: Compare server & client vnodes
    Vue Hydration->>Vue Hydration: data-allow-mismatch permits<br/>innerHTML differences
    Vue Hydration->>Browser: ✓ Hydration succeeds

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A script with patience found its way,
Through streams and vdoms, come what may,
With data-allow-mismatch grace,
Hydration blooms in every place!
✨📜🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main fix: symmetric HeadStream vnodes to enable clean streaming hydration by matching server and client vnode types.
Description check	✅ Passed	The description follows the template structure with all required sections: linked issue (N/A), type of change (bug fix selected), and detailed description explaining the problem, solution, and test plan.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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/streaming-hydration-mismatch

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

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

github-actions · 2026-04-22T14:26:18Z

Bundle Size Analysis

Bundle	Size	Gzipped
Client (Minimal)	10.7 kB	4.4 kB
Server (Minimal)	10.6 kB	4.3 kB
Vue Client (Minimal)	11.8 kB	4.9 kB
Vue Server (Minimal)	11.6 kB	4.7 kB

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@examples/vite-ssr-vue-streaming/tests/streaming.spec.ts`:
- Around line 237-245: The test currently only asserts unsafe === 0 which can
vacuously pass if no streamed update scripts were present; update the test to
also assert that at least one script containing "window.__unhead__.push" was
found. Locate the page.evaluate that collects script nodes (variable unsafe) and
either return a second value for the total matched scripts or run a separate
evaluate to count scripts that include 'window.__unhead__.push' (ignoring those
with data-allow-mismatch), then add an assertion like
expect(totalMatched).toBeGreaterThan(0) in addition to the existing
expect(unsafe).toBe(0) so the test fails when the HeadStream injection path
produced no scripts.

🪄 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: f6b44fcd-1b90-40e6-806f-da59fb4851bc

📥 Commits

Reviewing files that changed from the base of the PR and between 0c0feee and 7c73d4b.

📒 Files selected for processing (9)

examples/vite-ssr-vue-streaming/index.html
examples/vite-ssr-vue-streaming/src/App.vue
examples/vite-ssr-vue-streaming/src/entry-client.ts
examples/vite-ssr-vue-streaming/tests/streaming.spec.ts
packages/unhead/src/stream/server.ts
packages/vue/src/stream/client.ts
packages/vue/src/stream/server.ts
packages/vue/src/stream/vite.ts
packages/vue/test/streaming.test.ts

💤 Files with no reviewable changes (1)

examples/vite-ssr-vue-streaming/src/entry-client.ts

Streaming head updates were emitted as `<script innerHTML="...">` vnodes on the server but as `null` on the client, producing vnode-type hydration mismatches. `HeadStream` now emits a symmetric `<script data-allow-mismatch="children">` on both server and client. Server fills `innerHTML` with the pending suspense-chunk payload (or empty before the shell renders); client renders an empty script. Matching vnode types + `data-allow-mismatch` let Vue's hydrator silence the inner-text diff cleanly. Playwright adds a regression guard that every streamed head-update script carries `data-allow-mismatch` (and that at least one such script was injected so the check is non-vacuous).

coderabbitai Bot reviewed Apr 22, 2026

View reviewed changes

Comment thread examples/vite-ssr-vue-streaming/tests/streaming.spec.ts Outdated

harlan-zw force-pushed the fix/streaming-hydration-mismatch branch from 769eb10 to 7b3ead1 Compare April 22, 2026 14:46

harlan-zw changed the title ~~fix(vue): clean hydration for streaming SSR~~ fix(vue): symmetric HeadStream vnodes for clean streaming hydration Apr 22, 2026

harlan-zw mentioned this pull request Apr 22, 2026

fix(unhead): split streaming template at SSR outlet marker #750

Merged

6 tasks

harlan-zw merged commit e860d62 into main Apr 22, 2026
8 checks passed

This was referenced Apr 23, 2026

feat(stream): webpack plugin + bundler-agnostic factory #751

Merged

fix(vue): batch streamed head updates via self-deleting inline scripts #752

Merged

feat(stream): split template at  /  marker #753

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(vue): symmetric HeadStream vnodes for clean streaming hydration#748

fix(vue): symmetric HeadStream vnodes for clean streaming hydration#748
harlan-zw merged 1 commit into
mainfrom
fix/streaming-hydration-mismatch

harlan-zw commented Apr 22, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 22, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Poem

Uh oh!

github-actions Bot commented Apr 22, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

harlan-zw commented Apr 22, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Linked issue

❓ Type of change

📚 Description

✅ Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Poem

Uh oh!

github-actions Bot commented Apr 22, 2026

Bundle Size Analysis

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

harlan-zw commented Apr 22, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 22, 2026 •

edited

Loading