Registry / web-framework / vue3-lazy-hydration

vue3-lazy-hydration

library1.2.1jsnpmunverified

vue3-lazy-hydration is a library designed for Vue 3 applications utilizing Server-Side Rendering (SSR) to improve initial page load performance by delaying the hydration of pre-rendered HTML components. Instead of immediately making all components interactive on the client, it allows developers to specify conditions under which hydration should occur, such as when the browser is idle, when a component becomes visible in the viewport, or upon user interaction (e.g., click, focus). The library provides a flexible API including a renderless component (`LazyHydrationWrapper`), composables like `useLazyHydration`, and import wrappers for controlling hydration. The current stable version is 1.2.1. While the project saw several updates in 2022, its release cadence has since become dormant, with the last update in September 2022. It distinguishes itself by offering multiple hydration strategies and direct Vue 3 compatibility, building upon concepts from its Vue 2 predecessor.

web-framework

npm install vue3-lazy-hydration

github ↗package ↗

INSTALL

IMPORT

SIG · VUE3-LAZY-HYDRATIO

vue3-lazy-hydration

web-frameworkjavascriptv1.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LazyHydrationWrapper

✓ import { LazyHydrationWrapper } from 'vue3-lazy-hydration';

✗ const { LazyHydrationWrapper } = require('vue3-lazy-hydration');

CommonJS `require` syntax is not recommended for modern Vue 3 projects which primarily use ESM. Use named import for the component.

useLazyHydration

✓ import { useLazyHydration } from 'vue3-lazy-hydration';

A composable used to manually trigger or control hydration logic within a setup script. First mentioned in v1.0.0 features.

LazyHydrationOptions

✓ import type { LazyHydrationOptions } from 'vue3-lazy-hydration';

✗ import { LazyHydrationOptions } from 'vue3-lazy-hydration';

Since v1.2.0, type declarations are provided. Types should be imported using `import type` to ensure they are stripped from the JavaScript bundle.

This example demonstrates various lazy hydration strategies using the `LazyHydrationWrapper` component. It shows how to delay hydration until the browser is idle, when the component becomes visible in the viewport, or upon specific user interactions like click or touchstart. Each method logs a message and triggers an alert when the component successfully hydrates.

// App.vue <template> <div id="app"> <h1>Vue 3 Lazy Hydration Example</h1> <p>Component below will hydrate when the browser is idle (or after 4 seconds).</p> <LazyHydrationWrapper :when-idle="4000" @hydrated="onIdleHydrated"> <div class="card"> <h3>Idle Hydrated Component</h3> <p>This content was server-rendered and will become interactive when the browser is idle or after a 4s timeout.</p> <button @click="showMessage('Idle Button Clicked!')">Click Me</button> </div> </LazyHydrationWrapper> <p>Component below will hydrate when it becomes visible in the viewport.</p> <div style="height: 100vh;">Scroll down to see the next component</div> <LazyHydrationWrapper :when-visible="{ rootMargin: '50px' }" @hydrated="onVisibleHydrated"> <div class="card"> <h3>Visible Hydrated Component</h3> <p>This content was server-rendered and will become interactive when it enters the viewport.</p> <button @click="showMessage('Visible Button Clicked!')">Click Me</button> </div> </LazyHydrationWrapper> <p>Component below will hydrate on interaction (click or touchstart).</p> <LazyHydrationWrapper :on-interaction="['click', 'touchstart']" @hydrated="onInteractionHydrated"> <div class="card"> <h3>Interaction Hydrated Component</h3> <p>Click or touch this area to hydrate and make the button interactive.</p> <button @click="showMessage('Interaction Button Clicked!')">Click Me</button> </div> </LazyHydrationWrapper> </div> </template> <script setup lang="ts"> import { LazyHydrationWrapper } from 'vue3-lazy-hydration'; function onIdleHydrated() { console.log('Idle Hydration: Component is now interactive!'); alert('Idle Component Hydrated!'); } function onVisibleHydrated() { console.log('Visible Hydration: Component is now interactive!'); alert('Visible Component Hydrated!'); } function onInteractionHydrated() { console.log('Interaction Hydration: Component is now interactive!'); alert('Interaction Component Hydrated!'); } function showMessage(msg: string) { console.log(msg); alert(msg); } </script> <style> .card { border: 1px solid #ccc; padding: 20px; margin-bottom: 20px; border-radius: 8px; } </style>

Debug

Known issues

breakingPackage installation failed due to problematic pre/post install scripts. Versions before 1.2.1 included scripts that could cause npm/yarn installation failures when used as a dependency.

fix

Upgrade to `vue3-lazy-hydration@1.2.1` or newer using `npm install vue3-lazy-hydration@latest` or `yarn add vue3-lazy-hydration@latest`.

affects: >=1.0.0 <1.2.1

gotchaThe `vue3-lazy-hydration` package has not seen active development since September 2022. While functional for its intended purpose, long-term compatibility with newer Vue 3 versions or ecosystem changes is not guaranteed, and new features or bug fixes are unlikely.

fix

Evaluate if the current feature set meets your needs and consider the lack of ongoing support when planning for future updates or specific bug fixes. Keep an eye on the GitHub repository for any unexpected activity.

affects: >=1.2.1

gotchaUsing `LazyHydrationWrapper` without any `when-idle`, `when-visible`, `on-interaction`, or `manual` props will result in the component *never* hydrating. The content will remain static and non-interactive.

fix

Always provide at least one condition prop (e.g., `:when-idle`, `:when-visible`, `:on-interaction`) to ensure your component eventually hydrates and becomes interactive. If manual control is desired, use the `:manual` prop.

affects: >=1.0.0

Errors

Common errors & fixes

npm ERR! Lifecycle: `vue3-lazy-hydration@X.Y.Z install`

Malformed pre/post install scripts in earlier versions of the package (prior to v1.2.1).

fix

Update to `vue3-lazy-hydration@1.2.1` or newer by running `npm install vue3-lazy-hydration@latest` or `yarn add vue3-lazy-hydration@latest`.

[Vue warn]: A component that exports a `setup()` function must be called.

The `LazyHydrationWrapper` component was used without any hydration condition, leading to it never being hydrated and its setup function not being called on the client side.

fix

Ensure you provide a hydration trigger prop like `:when-idle`, `:when-visible`, `:on-interaction`, or `:manual` to the `LazyHydrationWrapper` component. Without these, the component will not hydrate and remain static.

Can't resolve 'vue3-lazy-hydration' in '...'

The package `vue3-lazy-hydration` is either not installed, or there's a typo in the import path.

fix

Verify the import statement `import { ... } from 'vue3-lazy-hydration';` is correct. Ensure the package is properly installed by running `npm install vue3-lazy-hydration` or `yarn add vue3-lazy-hydration`.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

vuerequiredPeer dependency for all Vue 3 applications. Required at runtime.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/freddy38510/vue3-lazy-hydration ↗

packagehttps://www.npmjs.com/package/vue3-lazy-hydration ↗