vue3-lazy-hydration

Lazy Hydration of Server-Side Rendered Vue.js v3 Components

Inspired by vue-lazy-hydration, this library brings a renderless component, composables and import wrappers to delay the hydration of pre-rendered HTML.

Installation

Use yarn v1, npm or pnpm package manager to install vue3-lazy-hydration.

# install with yarn
yarn add vue3-lazy-hydration

# install with npm
npm install vue3-lazy-hydration

# install with pnpm
pnpm add vue3-lazy-hydration

Importing Renderless Component

If you want to use the renderless component you can either import it directly inside your Vue SFCs (see examples below) or make it available globally.

Global import for Vue

import { createSSRApp } from 'vue';
import { LazyHydrationWrapper } from 'vue3-lazy-hydration';

const app = createSSRApp({});

app.component('LazyHydrationWrapper', LazyHydrationWrapper);

// or, you can use a custom registered name:
// use <LazyHydrate> instead of <LazyHydrationWrapper>
app.component('LazyHydrate', LazyHydrationWrapper);

Global import for Nuxt 3

Create a Nuxt 3 plugin inside the plugins directory. The filename doesn't matter as Nuxt auto-imports all top-level files of this directory.

// plugins/lazy-hydration.ts
import { LazyHydrationWrapper } from 'vue3-lazy-hydration';

export default defineNuxtPlugin((nuxtApp) => {
  // for custom registered name see Vue example above
  nuxtApp.vueApp.component('LazyHydrationWrapper', LazyHydrationWrapper);
});

Usage

Renderless Component

• Never hydrate.

  <template>
    <LazyHydrationWrapper @hydrated="onHydrated">
      <!--
        Content never hydrated.
      -->
    </LazyHydrationWrapper>
  </template>
  
  <script setup>
    import { LazyHydrationWrapper } from 'vue3-lazy-hydration';
  
    function onHydrated() {
      console.log('this function will never be called !');
    }
  </script>

• Delays hydration until the browser is idle.

  <template>
    <LazyHydrationWrapper :when-idle="4000" @hydrated="onHydrated">
      <!--
      Content hydrated when the browser is idle, or when the timeout
        of 4000ms has elapsed and hydration has not already taken place.
      -->
    </LazyHydrationWrapper>
  </template>
  <script setup>
    import { LazyHydrationWrapper } from 'vue3-lazy-hydration';
  
    function onHydrated() {
      console.log('content hydrated !');
    }
  </script>

• Delays hydration until one of the root elements is visible.

  <template>
    <LazyHydrationWrapper
      :when-visible="{ rootMargin: '50px' }"
      @hydrated="onHydrated"
    >
      <!--
      Content hydrated when one of the root elements is visible.
      All root elements are observed with a margin of 50px.
      -->
    </LazyHydrationWrapper>
  </template>
  
  <script setup>
    import { LazyHydrationWrapper } from 'vue3-lazy-hydration';
  
    function onHydrated() {
      console.log('content hydrated !');
    }
  </script>

• Delays hydration until one of the elements triggers a DOM event (focus by default).

  <template>
    <LazyHydrationWrapper
      :on-interaction="['click', 'touchstart']"
      @hydrated="onHydrated"
    >
      <!--
      Content hydrated when one of the elements triggers a click or touchstart event.
      -->
    </LazyHydrationWrapper>
  </template>
  
  <script setup>
    import { LazyHydrationWrapper } from 'vue3-lazy-hydration';
  
    function onHydrated() {
      console.log('content hydrated !');
    }
  </script>

• Delays hydration until manually triggered.

  <template>
    <button @click="triggerHydration">Trigger hydration</button>
  
    <LazyHydrationWrapper :when-triggered="triggered" @hydrated="onHydrated">
      <!--
      Content hydrated when the above button is clicked.
      -->
    </LazyHydrationWrapper>
  </template>
  
  <script setup>
    import { ref } from 'vue';
    import { LazyHydrationWrapper } from 'vue3-lazy-hydration';
  
    const triggered = ref(false);
  
    function triggerHydration() {
      triggered.value = true;
    }
  
    function onHydrated() {
      console.log('content hydrated !');
    }
  </script>

Props declaration

props: {

  /* Number type refers to the timeout option passed to the requestIdleCallback API
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback
  */
  whenIdle: {
    default: false,
    type: [Boolean, Number],
  },

  /* Object type refers to the options passed to the IntersectionObserver API
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
  */
  whenVisible: {
    default: false,
    type: [Boolean, Object],
  },

  /*
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Element#events
  */
  onInteraction: {
    default: false,
    type: [Array, Boolean, String],
  },

  /*
  * Object type refers to a ref object
  * @see https://vuejs.org/api/reactivity-core.html#ref
  */
  whenTriggered: {
    default: undefined,
    type: [Boolean, Object],
  },
}

Composables

useLazyHydration()

<script setup>
  import { useLazyHydration } from 'vue3-lazy-hydration';

  // delays hydration until hydrate function is called
  const { willPerformHydration, hydrate, onHydrated, onCleanup } =
    useLazyHydration();

  if (willPerformHydration === false) {
    /**
     * The application is actually running at server-side
     * or subsequent navigation occurred at client-side after the first load.
     */

    return;
  }

  // this hook is run when component is hydrated
  // and all its child asynchronous components are resolved
  onHydrated(() => {
    console.log('content hydrated !');
  });

  // this hook is run just before hydration
  onCleanup(() => {
    console.log('clean side effects (timeout, listeners, etc...)');
  });

  // optionnaly hydrate the component
  hydrate();
</script>

useHydrateWhenIdle({ willPerformHydration, hydrate, onCleanup }, timeout = 2000)

<script setup>
  import { useLazyHydration, useHydrateWhenIdle } from 'vue3-lazy-hydration';

  // delays hydration
  const { willPerformHydration, hydrate, onCleanup } = useLazyHydration();

  // hydrate when browser is idle
  // or when the timeout of 4000ms has elapsed
  // and the component has not already been hydrated
  useHydrateWhenIdle({ willPerformHydration, hydrate, onCleanup }, 4000);
</script>

useHydrateWhenVisible({ hydrate, onCleanup }, observerOpts = {})

<script setup>
  import { useLazyHydration, useHydrateWhenVisible } from 'vue3-lazy-hydration';

  // delays hydration
  const { willPerformHydration, hydrate, onCleanup } = useLazyHydration();

  // https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
  const observerOptions = {
    rootMargin: '0px',
    threshold: 1.0,
  };

  // hydrate when one of the root elements is visible
  useHydrateWhenVisible(
    { willPerformHydration, hydrate, onCleanup },
    observerOptions
  );
</script>

useHydrateOnInteraction({ hydrate, onCleanup }, events = ['focus'])

<script setup>
  import { useLazyHydration, useHydrateOnInteraction } from 'vue3-lazy-hydration';

  // delays hydration
  const { willPerformHydration, hydrate, onCleanup } = useLazyHydration();

  // hydrate when one of the elements triggers a focus or click event
  useHydrateOnInteraction({ willPerformHydration, hydrate, onCleanup }, ['focus' 'click']);
</script>

useHydrateWhenTriggered({ willPerformHydration, hydrate, onCleanup }, trigger)

<script setup>
  import { toRef } from 'vue';
  import {
    useLazyHydration,
    useHydrateWhenTriggered,
  } from 'vue3-lazy-hydration';

  const props = defineProps({
    triggerHydration: {
      default: undefined,
      type: [Boolean, Object],
    },
  });

  // delays hydration
  const result = useLazyHydration();

  // trigger hydration when the triggerHydration property changes to true
  useHydrateWhenTriggered(result, toRef(props, 'triggerHydration'));
</script>

Import Wrappers

hydrateNever(source)

Wrap a component in a renderless component that will never be hydrated.

<script setup>
  import { resolveComponent } from 'vue';

  import { hydrateNever } from 'vue3-lazy-hydration';

  // wrap a globally registered component resolved by its name
  const NeverHydratedComp = hydrateNever(resolveComponent('ComponentA'));

  // wrap an asynchronously loaded component
  const NeverHydratedAsyncComp = hydrateNever(() => import('./ComponentB.vue'));
</script>

<template>
  <NeverHydratedComp />

  <NeverHydratedAsyncComp />
</template>

hydrateWhenIdle(source, timeout = 2000)

Wrap a component in a renderless component that will be hydrated when browser is idle.

<script setup>
  import { resolveComponent } from 'vue';

  import { hydrateWhenIdle } from 'vue3-lazy-hydration';

  // wrap a globally registered component resolved by its name
  const LazilyHydratedComp = hydrateWhenIdle(
    resolveComponent('ComponentA'),
    2000
  );

  // wrap an asynchronously loaded component
  const LazilyHydratedAsyncComp = hydrateWhenIdle(
    () => import('./ComponentB.vue'),
    4000
  );
</script>

<template>
  <LazilyHydratedComp />

  <LazilyHydratedAsyncComp />
</template>

hydrateWhenVisible(source, observerOpts = {})

Wrap a component in a renderless component that will be hydrated when one of the root elements is visible.

<script setup>
  import { resolveComponent } from 'vue';

  import { hydrateWhenVisible } from 'vue3-lazy-hydration';

  // wrap a globally registered component resolved by its name
  const LazilyHydratedComp = hydrateWhenVisible(
    resolveComponent('ComponentA'),
    { rootMargin: '50px' }
  );

  // wrap an asynchronously loaded component
  const LazilyHydratedAsyncComp = hydrateWhenVisible(
    () => import('./ComponentB.vue'),
    {
      threshold: [0, 0.25, 0.5, 0.75, 1],
    }
  );
</script>

<template>
  <LazilyHydratedComp />

  <LazilyHydratedAsyncComp />
</template>

hydrateOnInteraction(source, events = ['focus'])

Wrap a component in a renderless component that will be hydrated when one of the elements trigger one of the events in the events parameter.

<script setup>
  import { resolveComponent } from 'vue';

  import { hydrateOnInteraction } from 'vue3-lazy-hydration';

  // wrap a globally registered component resolved by its name
  const LazilyHydratedComp = hydrateOnInteraction(
    resolveComponent('ComponentA')
  );

  // wrap an asynchronously loaded component
  const LazilyHydratedAsyncComp = hydrateOnInteraction(
    () => import('./ComponentB.vue'),
    ['focus', 'click', 'touchstart']
  );
</script>

<template>
  <LazilyHydratedComp />

  <LazilyHydratedAsyncComp />
</template>

hydrateWhenTriggered(source, trigger)

Wrap a component in a renderless component that will be hydrated when the trigger parameter changes to true.

<script setup>
  import { ref, resolveComponent } from 'vue';

  import { hydrateOnInteraction } from 'vue3-lazy-hydration';

  const hydrationTriggered = ref(false);

  // wrap a globally registered component resolved by its name
  const LazilyHydratedComp = hydrateOnInteraction(
    resolveComponent('ComponentA'),
    hydrationTriggered
  );

  // wrap an asynchronously loaded component
  const LazilyHydratedAsyncComp = hydrateOnInteraction(
    () => import('./ComponentB.vue'),
    hydrationTriggered
  );

  function triggerHydration() => {
    hydrationTriggered.value = true
  }
</script>

<template>
  <button @click="triggerHydration">Trigger</button>

  <LazilyHydratedComp />

  <LazilyHydratedAsyncComp />
</template>

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update unit tests as appropriate.

Development

Use the pnpm package manager to install vue3-lazy-hydration.

1. Clone the repository

   git clone https://github.com/freddy38510/vue3-lazy-hydration.git
   
   cd vue3-lazy-hydration

2. Install dependencies

   pnpm i

3. Start the development server which hosts a demo application to help develop the library

   pnpm dev

Credits

Many thanks to Markus Oberlehner, the author of the package vue-lazy-hydration.

License

MIT