feat: lazy hydration

packages/nuxt/src/app/components/nuxt-link.ts

@@ -14,6 +14,7 @@ import { onNuxtReady } from '../composables/ready'
 import { navigateTo, useRouter } from '../composables/router'
 import { useNuxtApp, useRuntimeConfig } from '../nuxt'
 import { cancelIdleCallback, requestIdleCallback } from '../compat/idle-callback'
+import { useObserver } from '../utils'
 
 // @ts-expect-error virtual file
 import { nuxtLinkDefaults } from '#build/nuxt.config.mjs'
@@ -435,49 +436,6 @@ function applyTrailingSlashBehavior (to: string, trailingSlash: NuxtLinkOptions[
 }
 
 // --- Prefetching utils ---
-type CallbackFn = () => void
-type ObserveFn = (element: Element, callback: CallbackFn) => () => void
-
-function useObserver (): { observe: ObserveFn } | undefined {
-  if (import.meta.server) { return }
-
-  const nuxtApp = useNuxtApp()
-  if (nuxtApp._observer) {
-    return nuxtApp._observer
-  }
-
-  let observer: IntersectionObserver | null = null
-
-  const callbacks = new Map<Element, CallbackFn>()
-
-  const observe: ObserveFn = (element, callback) => {
-    if (!observer) {
-      observer = new IntersectionObserver((entries) => {
-        for (const entry of entries) {
-          const callback = callbacks.get(entry.target)
-          const isVisible = entry.isIntersecting || entry.intersectionRatio > 0
-          if (isVisible && callback) { callback() }
-        }
-      })
-    }
-    callbacks.set(element, callback)
-    observer.observe(element)
-    return () => {
-      callbacks.delete(element)
-      observer!.unobserve(element)
-      if (callbacks.size === 0) {
-        observer!.disconnect()
-        observer = null
-      }
-    }
-  }
-
-  const _observer = nuxtApp._observer = {
-    observe,
-  }
-
-  return _observer
-}
 
 function isSlowConnection () {
   if (import.meta.server) { return }

packages/nuxt/src/app/utils.ts

@@ -1,4 +1,49 @@
-/** @since 3.9.0 */
+import { useNuxtApp } from './nuxt'
+
 export function toArray<T> (value: T | T[]): T[] {
   return Array.isArray(value) ? value : [value]
 }
+
+type CallbackFn = () => void
+type ObserveFn = (element: Element, callback: CallbackFn) => () => void
+
+export function useObserver (): { observe: ObserveFn } | undefined {
+  if (import.meta.server) { return }
+
+  const nuxtApp = useNuxtApp()
+  if (nuxtApp._observer) {
+    return nuxtApp._observer
+  }
+
+  let observer: IntersectionObserver | null = null
+
+  const callbacks = new Map<Element, CallbackFn>()
+
+  const observe: ObserveFn = (element, callback) => {
+    if (!observer) {
+      observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+          const callback = callbacks.get(entry.target)
+          const isVisible = entry.isIntersecting || entry.intersectionRatio > 0
+          if (isVisible && callback) { callback() }
+        }
+      })
+    }
+    callbacks.set(element, callback)
+    observer.observe(element)
+    return () => {
+      callbacks.delete(element)
+      observer!.unobserve(element)
+      if (callbacks.size === 0) {
+        observer!.disconnect()
+        observer = null
+      }
+    }
+  }
+
+  const _observer = nuxtApp._observer = {
+    observe,
+  }
+
+  return _observer
+}

packages/nuxt/src/components/loader.ts

@@ -21,7 +21,7 @@ export const loaderPlugin = createUnplugin((options: LoaderOptions) => {
   const exclude = options.transform?.exclude || []
   const include = options.transform?.include || []
   const serverComponentRuntime = resolve(distDir, 'components/runtime/server-component')
-
+  const clientDelayedComponentRuntime = resolve(distDir, 'components/runtime/client-delayed-component')
   return {
     name: 'nuxt:components-loader',
     enforce: 'post',
@@ -72,9 +72,17 @@ export const loaderPlugin = createUnplugin((options: LoaderOptions) => {
           }
 
           if (lazy) {
-            imports.add(genImport('vue', [{ name: 'defineAsyncComponent', as: '__defineAsyncComponent' }]))
-            identifier += '_lazy'
-            imports.add(`const ${identifier} = __defineAsyncComponent(${genDynamicImport(component.filePath, { interopDefault: false })}.then(c => c.${component.export ?? 'default'} || c)${isClientOnly ? '.then(c => createClientOnly(c))' : ''})`)
+            // Temporary hardcoded check to verify runtime functionality
+            if (name === 'DelayedWrapperTestComponent') {
+              imports.add(genImport('vue', [{ name: 'defineAsyncComponent', as: '__defineAsyncComponent' }]))
+              imports.add(genImport(clientDelayedComponentRuntime, [{ name: 'createLazyIOClientPage' }]))
+              identifier += '_delayedIO'
+              imports.add(`const ${identifier} = createLazyIOClientPage(__defineAsyncComponent(${genDynamicImport(component.filePath, { interopDefault: false })}.then(c => c.${component.export ?? 'default'} || c)))`)
+            } else {
+              imports.add(genImport('vue', [{ name: 'defineAsyncComponent', as: '__defineAsyncComponent' }]))
+              identifier += '_lazy'
+              imports.add(`const ${identifier} = __defineAsyncComponent(${genDynamicImport(component.filePath, { interopDefault: false })}.then(c => c.${component.export ?? 'default'} || c)${isClientOnly ? '.then(c => createClientOnly(c))' : ''})`)
+            }
           } else {
             imports.add(genImport(component.filePath, [{ name: component._raw ? 'default' : component.export, as: identifier }]))
 

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

@@ -0,0 +1,91 @@
+import { createStaticVNode, createVNode, defineComponent, getCurrentInstance, h, onBeforeUnmount, onMounted, ref } from 'vue'
+import type { Component, Ref, VNode } from 'vue'
+// import ClientOnly from '#app/components/client-only'
+import { useObserver } from '#app/utils'
+import { getFragmentHTML } from '#app/components/utils'
+import { useNuxtApp } from '#app/nuxt'
+
+// todo find a better way to do it ?
+function elementIsVisibleInViewport (el: Element) {
+  const { top, left, bottom, right } = el.getBoundingClientRect()
+  const { innerHeight, innerWidth } = window
+  return ((top > 0 && top < innerHeight) ||
+    (bottom > 0 && bottom < innerHeight)) &&
+    ((left > 0 && left < innerWidth) || (right > 0 && right < innerWidth))
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export const createLazyIOClientPage = (componentLoader: Component) => {
+  return defineComponent({
+    inheritAttrs: false,
+    setup (_, { attrs }) {
+      if (import.meta.server) {
+        return () => h('div', {}, [
+          h(componentLoader, attrs),
+        ])
+      }
+
+      const nuxt = useNuxtApp()
+      const instance = getCurrentInstance()!
+      const isIntersecting = ref(false)
+      const el: Ref<Element | null> = ref(null)
+      let unobserve: (() => void) | null = null
+
+      // todo can be refactored
+      if (instance.vnode.el && nuxt.isHydrating) {
+        isIntersecting.value = elementIsVisibleInViewport(instance.vnode.el as Element)
+      }
+
+      if (!isIntersecting.value) {
+        onMounted(() => {
+          const observer = useObserver()
+          unobserve = observer!.observe(el.value as Element, () => {
+            isIntersecting.value = true
+            unobserve?.()
+            unobserve = null
+          })
+        })
+      }
+      onBeforeUnmount(() => {
+        unobserve?.()
+        unobserve = null
+      })
+      return () => {
+        return h('div', { ref: el }, [
+          isIntersecting.value ? h(componentLoader, attrs) : (instance.vnode.el && nuxt.isHydrating) ? createVNode(createStaticVNode(getFragmentHTML(instance.vnode.el ?? null, true)?.join('') || '', 1)) : null,
+        ])
+      }
+    },
+  })
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export const createLazyNetworkClientPage = (componentLoader: Component) => {
+  return defineComponent({
+    inheritAttrs: false,
+    setup (_, { attrs }) {
+      const nuxt = useNuxtApp()
+      const instance = getCurrentInstance()!
+      let vnode: VNode | null = null
+      if (import.meta.client && nuxt.isHydrating && instance.vnode?.el) {
+        vnode = createStaticVNode(getFragmentHTML(instance.vnode.el ?? null, true)?.join('') || '', 1)
+      }
+      const isIdle = ref(false)
+      let idleHandle: number | null = null
+      onMounted(() => {
+        idleHandle = requestIdleCallback(() => {
+          isIdle.value = true
+          cancelIdleCallback(idleHandle as unknown as number)
+          idleHandle = null
+        })
+      })
+      onBeforeUnmount(() => {
+        if (idleHandle) {
+          cancelIdleCallback(idleHandle as unknown as number)
+          idleHandle = null
+        }
+      })
+      return () => isIdle.value ? h(componentLoader, attrs) : vnode
+    },
+  })
+}

packages/schema/src/config/experimental.ts

@@ -238,6 +238,13 @@ export default defineUntypedSchema({
       },
     },
 
+    /**
+     * Experimental built-in delayed component hydration
+     *
+     * This enables components to lazily hydrate when needed, improving performance for sites with components below-the-fold
+     */
+    componentLazyHydration: false,
+
     /**
      * Config schema support
      * @see [Nuxt Issue #15592](https://github.com/nuxt/nuxt/issues/15592)

test/basic.test.ts

@@ -2604,4 +2604,13 @@
   it('lazy load named component with mode server', () => {
     expect(html).toContain('lazy-named-comp-server')
   })
+
+  it('lazy load delayed hydration comps at the right time', async () => {
+    expect(html).not.toContain('This shouldn\'t be visible at first!')
+    const { page } = await renderPage('/lazy-import-components')
+    expect(await page.locator('body').getByText('This shouldn\'t be visible at first!').all()).toHaveLength(1)
+    const response = page.waitForResponse(response => response.url().includes('DelayedWrapperTestComponent') && response.status() === 200)
+    await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))
+    await response
+  })
 })

test/fixtures/basic/components/DelayedWrapperTestComponent.vue

@@ -0,0 +1,5 @@
+<template>
+  <div>
+    This shouldn't be visible at first!
+  </div>
+</template>

test/fixtures/basic/pages/lazy-import-components/index.vue

@@ -3,5 +3,9 @@
     <LazyNCompAll message="lazy-named-comp-all" />
     <LazyNCompClient message="lazy-named-comp-client" />
     <LazyNCompServer message="lazy-named-comp-server" />
+    <div style="height:3000px">
+      This is a very tall div
+    </div>
+    <LazyDelayedWrapperTestComponent />
   </div>
 </template>

test/fixtures/basic/server/plugins/basicRenderDelayedHydration.ts

@@ -0,0 +1,5 @@
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('render:html', (html, { event }) => {
+    html.head = html.head.map((headSection: string) => headSection.replace(/<link((?=[^>]+\bhref="\/_nuxt\/DelayedWrapperTestComponent\.([^.]+?)\.js")[^>]+>)/, '')) // .replace(/<link rel="preload" href="\/_nuxt\/DelayedWrapperTestComponent\.js" as="script">/, "")
+  })
+})