feat(nuxt): delayed/lazy hydration support #26468

GalacticHypernova · 2024-03-24T17:34:23Z

🔗 Linked issue

Resolves #24242

❓ Type of change

👌 Enhancement (improving an existing functionality like performance)
✨ New feature (a non-breaking change that adds functionality)

📚 Description

Lazy components are great for controlling the chunk sizes in your app, but they don't always enhance runtime performance, as they still load eagerly unless conditionally rendered. In real-world applications, some pages may include a lot of content and a lot of components, and most of the time not all of them need to be interactive as soon as the page is loaded. Having them all load eagerly can negatively impact performance.

In order to optimize your app, you may want to delay the hydration of some components until they're visible, or until the browser is done with more important tasks.

Nuxt supports this using lazy (or delayed) hydration, allowing you to control when components become interactive.

Hydration Strategies

Nuxt provides a range of built-in hydration strategies. Only one strategy can be used per lazy component.

::warning
Currently Nuxt's built-in lazy hydration only works in single-file components (SFCs), and requires you to define the prop in the template (rather than spreading an object of props via v-bind).
::

`hydrate-on-visible`

Hydrates the component when it becomes visible in the viewport.

<template>
  <div>
    <LazyMyComponent hydrate-on-visible />
  </div>
</template>

::read-more{to="https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver" title="IntersectionObserver options"}
Read more about the options for hydrate-on-visible.
::

::note
Under the hood, this uses Vue's built-in hydrateOnVisible strategy.
::

`hydrate-on-idle`

Hydrates the component when the browser is idle. This is suitable if you need the component to load as soon as possible, but not block the critical rendering path.

You can also pass a number which serves as a max timeout.

<template>
  <div>
    <LazyMyComponent hydrate-on-idle />
  </div>
</template>

::note
Under the hood, this uses Vue's built-in hydrateOnIdle strategy.
::

`hydrate-on-interaction`

Hydrates the component after a specified interaction (e.g., click, mouseover).

<template>
  <div>
    <LazyMyComponent hydrate-on-interaction="mouseover" />
  </div>
</template>

If you do not pass an event or list of events, it defaults to hydrating on pointerenter and focus.

::note
Under the hood, this uses Vue's built-in hydrateOnInteraction strategy.
::

`hydrate-on-media-query`

Hydrates the component when the window matches a media query.

<template>
  <div>
    <LazyMyComponent hydrate-on-media-query="(max-width: 768px)" />
  </div>
</template>

::note
Under the hood, this uses Vue's built-in hydrateOnMediaQuery strategy.
::

`hydrate-after`

Hydrates the component after a specified delay (in milliseconds).

<template>
  <div>
    <LazyMyComponent :hydrate-after="2000" />
  </div>
</template>

`hydrate-when`

Hydrates the component based on a boolean condition.

<template>
  <div>
    <LazyMyComponent :hydrate-when="isReady" />
  </div>
</template>
<script setup lang="ts">
const isReady = ref(false)
function myFunction() {
  // trigger custom hydration strategy...
  isReady.value = true
}
</script>

`hydrate-never`

Never hydrates the component.

<template>
  <div>
    <LazyMyComponent hydrate-never />
  </div>
</template>

Listening to Hydration Events

All delayed hydration components emit a @hydrated event when they are hydrated.

<template>
  <div>
    <LazyMyComponent hydrate-on-visible @hydrated="onHydrated" />
  </div>
</template>

<script setup lang="ts">
function onHydrate() {
  console.log("Component has been hydrated!")
}
</script>

bolt-new-by-stackblitz · 2024-03-24T17:34:25Z

Run & review this pull request in StackBlitz Codeflow.

packages/nuxt/src/components/runtime/client-delayed-component.ts

…t.vue

…r.vue

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (9)

docs/2.guide/2.directory-structure/1.components.md (2)
128-129: Consider making the wording more concise.

The phrase "a lot of content and a lot of components" can sound repetitive. Try rephrasing to reduce wordiness.

🧰 Tools

🪛 LanguageTool

[style] ~128-~128: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ... pages may include a lot of content and a lot of components, and most of the time not al...

(A_LOT_OF)

[style] ~129-~129: Consider a shorter alternative to avoid wordiness.
Context: ...rly can negatively impact performance. In order to optimize your app, you may want to dela...

(IN_ORDER_TO_PREMIUM)

512-514: Add a comma for clarity.

Consider adding a comma before “and you can’t” to separate the clauses and enhance readability.
- * You can't access the 'island context' from the rest of your app and you can't access ...
+ * You can't access the 'island context' from the rest of your app, and you can't access ...
🧰 Tools

🪛 LanguageTool

[uncategorized] ~514-~514: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...sland context' from the rest of your app and you can't access the context of the res...

(COMMA_COMPOUND_SENTENCE)
packages/nuxt/test/component-loader.test.ts (2)
91-124: Multiple lazy hydration strategies are well tested.

The tests cover various strategies effectively. Consider including a conflicting strategy scenario to confirm fallback or prioritisation behaviour.

126-172: Add resource cleanup for Rollup bundles.

Wrap Rollup usage in a try/finally block to ensure bundles are closed, preventing potential memory leaks during repeated tests.
 async function transform (code: string, filename: string) {
+  let bundle
   try {
-    const bundle = await rollup({
+    bundle = await rollup({
       input: filename,
       plugins: [
         // ...
       ]
     })
     const { output: [chunk] } = await bundle.generate({})
     return chunk.code.trim()
+  } finally {
+    if (bundle) {
+      await bundle.close()
+    }
   }
 }
packages/nuxt/src/components/plugins/loader.ts (2)

24-24: Regex complexity caution.

This expanded regex handles multiple modifiers. Consider extracting some handling into helper functions or composable logic for better maintainability.

86-137: Consider splitting out each hydration strategy.

The switch-case approach is straightforward but large. Extracting each strategy into a helper method would aid readability and simplify future expansions.
packages/nuxt/src/components/runtime/lazy-hydrated-component.ts (3)
15-15: Consider handling potential undefined values more explicitly.

The non-null assertion operators (!) suggest that ssrContext or modules might be undefined in some cases, which could lead to runtime errors.
- ssrContext!.modules!.delete(id)
+ if (ssrContext?.modules) {
+   ssrContext.modules.delete(id)
+ }
31-38: Type casting approach could be improved for better clarity.

The type casting using as unknown as may be necessary due to TypeScript limitations, but it reduces type safety.

Consider adding a clear comment explaining the reason for this type casting approach, or if possible, use a more type-safe approach:
  hydrateOnVisible: {
-    type: [Object, Boolean] as unknown as () => true | IntersectionObserverInit,
+    // Cast needed to support both boolean and IntersectionObserverInit types
+    type: [Object, Boolean] as unknown as () => true | IntersectionObserverInit,
    required: false,
  },
105-114: Add a comment to explain the never-hydrate strategy.

The hydrateNever function is a simple empty function, which effectively prevents hydration. A comment explaining this would help other developers understand the intention.
- const hydrateNever = () => {}
+ // This function purposely does nothing, effectively preventing the component from ever hydrating
+ const hydrateNever = () => {}

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3349bf0 and 81a549b.

📒 Files selected for processing (4)

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

🧰 Additional context used

🧠 Learnings (1)

packages/nuxt/src/components/plugins/loader.ts (1)

Learnt from: GalacticHypernova
PR: nuxt/nuxt#26468
File: packages/nuxt/src/components/plugins/loader.ts:24-24
Timestamp: 2024-11-12T07:37:17.193Z
Learning: In `packages/nuxt/src/components/plugins/loader.ts`, the references to `resolve` and `distDir` are legacy code from before Nuxt used the new unplugin VFS and will be removed.

🪛 LanguageTool

docs/2.guide/2.directory-structure/1.components.md

[style] ~128-~128: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ... pages may include a lot of content and a lot of components, and most of the time not al...

(A_LOT_OF)

[style] ~129-~129: Consider a shorter alternative to avoid wordiness.
Context: ...rly can negatively impact performance. In order to optimize your app, you may want to dela...

(IN_ORDER_TO_PREMIUM)

[uncategorized] ~137-~137: Loose punctuation mark.
Context: ...rategy can be used per lazy component. ::warning Currently Nuxt's built-in lazy ...