perf(nuxt): remove watcher from `hydrate-when` lazy hydration strategy #33199

cernymatej · 2025-09-10T17:24:40Z

🔗 Linked issue

resolves #33193

📚 Description

I noticed that any prop change on a component using lazy hydration in Vue will cause it to hydrate. This means that it is not necessary to call the hydrate function in the hydrate-when strategy, and actually, doing so produces a warning in dev mode (vuejs/core#13283).

This PR removes the watcher, which calls hydrate() unnecessarily in the next tick and also updates the docs.

Could this cause a problem in some cases?

bolt-new-by-stackblitz · 2025-09-10T17:24:44Z

Run & review this pull request in StackBlitz Codeflow.

pkg-pr-new · 2025-09-10T17:28:33Z

Open in StackBlitz

@nuxt/kit

npm i https://pkg.pr.new/@nuxt/kit@33199

nuxt

npm i https://pkg.pr.new/nuxt@33199

@nuxt/rspack-builder

npm i https://pkg.pr.new/@nuxt/rspack-builder@33199

@nuxt/schema

npm i https://pkg.pr.new/@nuxt/schema@33199

@nuxt/vite-builder

npm i https://pkg.pr.new/@nuxt/vite-builder@33199

@nuxt/webpack-builder

npm i https://pkg.pr.new/@nuxt/webpack-builder@33199

commit: dc51b96

coderabbitai · 2025-09-10T17:31:06Z

Walkthrough

Documentation: Added notes under Hydration Strategies explaining that any prop change on a lazily hydrated component triggers immediate hydration, plus warnings about current limitations (SFC-only, prop must be explicitly in template, not via v-bind spread, and not usable with direct imports from #components).
Runtime: In lazy-hydrated-component.ts, removed Vue watch-based hydration trigger; the else-branch now no-ops, relying on Vue to hydrate automatically when the hydrateWhen prop changes. No public API changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Small scope: one runtime file with a straightforward removal of a watcher and corresponding logic, plus documentation updates. Low heterogeneity and limited logic density; focused verification around hydration behaviour change.

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

Pre-merge checks (5 passed)

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly describes the main change by indicating the removal of the watcher from the `hydrate-when` lazy hydration strategy in Nuxt, reflecting the principal performance improvement without extraneous detail.
Linked Issues Check	✅ Passed	The pull request addresses the core objective of linked issue #33193 by removing the unnecessary watcher that triggered skipped hydration warnings, thereby preventing the console warning and aligning with Vue’s lazy hydration semantics.
Out of Scope Changes Check	✅ Passed	All modifications are confined to removing the watcher logic in `lazy-hydrated-component.ts` and updating the corresponding documentation; there are no unrelated or extraneous changes outside the issue’s scope.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	The PR description directly references the linked issue (#33193), describes the observed Vue warning and reproduction context, and explains the proposed change (removing the watcher and updating docs) with rationale and an illustrative screenshot; this closely matches the changes in the diff and is therefore relevant to the changeset.

✨ Finishing touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment

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.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/2.guide/2.directory-structure/1.app/1.components.md (1)
136-139: Clarify that this is a forced hydration (incl. hydrate-never) and tighten wording

Minor phrasing to align with Vue’s behaviour and avoid confusion about “never”:
-::note
-Any prop change on a lazily hydrated component will trigger hydration immediately. (e.g., changing a prop on a component with `hydrate-never` will cause it to hydrate)
-::
+::note
+Any prop change to a lazily hydrated component will cause Vue to skip the lazy strategy and hydrate immediately — including `hydrate-never`. This is expected behaviour in Vue.
+::

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4b46681 and dc51b96.

📒 Files selected for processing (2)

docs/2.guide/2.directory-structure/1.app/1.components.md (1 hunks)
packages/nuxt/src/components/runtime/lazy-hydrated-component.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Follow standard TypeScript conventions and best practices

Files:

packages/nuxt/src/components/runtime/lazy-hydrated-component.ts

🧠 Learnings (3)

📓 Common learnings

Learnt from: Tofandel
PR: nuxt/nuxt#26468
File: packages/nuxt/src/components/runtime/client-delayed-component.ts:62-62
Timestamp: 2024-11-05T20:04:39.622Z
Learning: In Vue components, when typing the `hydrate` prop for hydration strategies like `hydrateOnInteraction`, use `type: null as PropType<Arguments<typeof hydrateOnInteraction>[0]>` to get the type directly from Vue's hydration methods. Also, remember that `HTMLElementEventMap` is not a type but an object; use `keyof HTMLElementEventMap` when defining prop types for events.

📚 Learning: 2024-11-05T20:04:39.622Z

Learnt from: Tofandel
PR: nuxt/nuxt#26468
File: packages/nuxt/src/components/runtime/client-delayed-component.ts:62-62
Timestamp: 2024-11-05T20:04:39.622Z
Learning: In Vue components, when typing the `hydrate` prop for hydration strategies like `hydrateOnInteraction`, use `type: null as PropType<Arguments<typeof hydrateOnInteraction>[0]>` to get the type directly from Vue's hydration methods. Also, remember that `HTMLElementEventMap` is not a type but an object; use `keyof HTMLElementEventMap` when defining prop types for events.

Applied to files:

docs/2.guide/2.directory-structure/1.app/1.components.md
packages/nuxt/src/components/runtime/lazy-hydrated-component.ts

📚 Learning: 2024-12-12T12:36:34.871Z

Learnt from: huang-julien
PR: nuxt/nuxt#29366
File: packages/nuxt/src/app/components/nuxt-root.vue:16-19
Timestamp: 2024-12-12T12:36:34.871Z
Learning: In `packages/nuxt/src/app/components/nuxt-root.vue`, when optimizing bundle size by conditionally importing components based on route metadata, prefer using inline conditional imports like:

```js
const IsolatedPage = route?.meta?.isolate ? defineAsyncComponent(() => import('#build/isolated-page.mjs')) : null
```

instead of wrapping the import in a computed property or importing the component unconditionally.

Applied to files:

packages/nuxt/src/components/runtime/lazy-hydrated-component.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (20)

GitHub Check: test-fixtures (ubuntu-latest, built, webpack, default, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (windows-latest, built, rspack, async, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (windows-latest, dev, vite, default, manifest-off, json, lts/-1)
GitHub Check: test-fixtures (windows-latest, built, vite, async, manifest-off, json, lts/-1)
GitHub Check: test-fixtures (windows-latest, dev, vite, async, manifest-off, json, lts/-1)
GitHub Check: test-fixtures (windows-latest, dev, vite, async, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, built, vite, async, manifest-on, js, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, built, vite, default, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, built, vite, async, manifest-off, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, dev, vite, default, manifest-off, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, dev, vite, async, manifest-off, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, dev, vite, async, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, dev, vite, async, manifest-on, js, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, dev, vite, default, manifest-on, json, lts/-1)
GitHub Check: release-pkg-pr-new
GitHub Check: typecheck (ubuntu-latest, bundler)
GitHub Check: test-size
GitHub Check: test-benchmark
GitHub Check: code

🔇 Additional comments (2)

packages/nuxt/src/components/runtime/lazy-hydrated-component.ts (2)

1-1: Good removal of the watcher import

Dropping watch eliminates redundant scheduling and the dev warning source. LGTM.

84-87: Existing hydrate-when tests already cover toggle; noop signature is type-compatible—no changes required.

codspeed-hq · 2025-09-10T17:39:41Z

CodSpeed Performance Report

Merging #33199 will not alter performance

_{Comparing cernymatej:perf/remove-hydrate-when-watcher (dc51b96) with main (4b46681)}

Summary

✅ 10 untouched benchmarks

#33199)

perf(nuxt): remove watcher from hydrate-when lazy hydration strategy

dc51b96

cernymatej requested a review from danielroe as a code owner September 10, 2025 17:24

github-actions bot added 4.x performance labels Sep 10, 2025

coderabbitai bot reviewed Sep 10, 2025

View reviewed changes

danielroe approved these changes Sep 11, 2025

View reviewed changes

danielroe merged commit eb8d779 into nuxt:main Sep 11, 2025
49 of 51 checks passed

cernymatej deleted the perf/remove-hydrate-when-watcher branch September 11, 2025 11:47

github-actions bot mentioned this pull request Sep 11, 2025

v4.1.2 #33155

Merged

danielroe pushed a commit that referenced this pull request Sep 12, 2025

perf(nuxt): remove watcher from hydrate-when lazy hydration strategy (

2e82711

#33199)

github-actions bot mentioned this pull request Sep 11, 2025

v3.19.2 #33171

Merged

chrisbbreuer mentioned this pull request Sep 12, 2025

chore(deps): update all non-major dependencies stacksjs/ts-maps#80

Closed

1 task

chrisbbreuer mentioned this pull request Sep 28, 2025

chore(deps): update all non-major dependencies stacksjs/ts-maps#327

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

perf(nuxt): remove watcher from `hydrate-when` lazy hydration strategy #33199

perf(nuxt): remove watcher from `hydrate-when` lazy hydration strategy #33199

Uh oh!

cernymatej commented Sep 10, 2025 •

edited

Loading

Uh oh!

bolt-new-by-stackblitz bot commented Sep 10, 2025

Uh oh!

pkg-pr-new bot commented Sep 10, 2025

Uh oh!

coderabbitai bot commented Sep 10, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

codspeed-hq bot commented Sep 10, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

perf(nuxt): remove watcher from hydrate-when lazy hydration strategy #33199

perf(nuxt): remove watcher from hydrate-when lazy hydration strategy #33199

Uh oh!

Conversation

cernymatej commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Linked issue

📚 Description

Uh oh!

bolt-new-by-stackblitz bot commented Sep 10, 2025

Uh oh!

pkg-pr-new bot commented Sep 10, 2025

Uh oh!

coderabbitai bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

Pre-merge checks (5 passed)

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

codspeed-hq bot commented Sep 10, 2025

CodSpeed Performance Report

Merging #33199 will not alter performance

Summary

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

perf(nuxt): remove watcher from `hydrate-when` lazy hydration strategy #33199

perf(nuxt): remove watcher from `hydrate-when` lazy hydration strategy #33199

cernymatej commented Sep 10, 2025 •

edited

Loading

coderabbitai bot commented Sep 10, 2025 •

edited

Loading