harlan-zw / nuxt-delay-hydration

Delay Hydration for Nuxt.js! ⚡️
^{Improve your Nuxt.js v2 Google Lighthouse score by delaying hydration ⚡️}

Status: Stable v2 ✅ , bridge ❌ , v3 ❌️ Made possible by my Sponsor Program 💖 Follow me @harlan_zw 🐦

Features

• ⚡️ Instantly increase your Google Lighthouse score
• 🔥 Reduce your "Blocking Time" by as much as 100%
• 🍃 Pre-configured to minimise user experience issues
• 🔁 (optional) Replay pre-hydration clicks

Install

yarn add nuxt-delay-hydration
# npm i nuxt-delay-hydration

Requirement: SSR, full-static (SSG) is highly recommended.

Usage

Within your nuxt.config.js add the following.

// nuxt.config.js
export default {
  buildModules: [
    'nuxt-delay-hydration',
  ],
}

Note: The module will not run in development unless you have enabled debug.

Choosing a mode

By default, no mode is selected, you will need to select how you would the module to work.

Type: init | mount| manual | false

Default: false

Regardless of the mode you choose, please read further optimisations.

Init Mode

Delays hydration before the Nuxt app is created. Your entire app, including plugins, will be delayed. This will provide the biggest speed improvements however is the riskiest and may increase other metrics with delayed network requests.

Pros: Provides the biggest blocking time reduction

Cons: Risky if you have critical third party scripts

Benchmark: ~90-100% reduction

export default {
  delayHydration: {
    mode: 'init'
  }
}

Mount Mode

Delays hydration once your app is created (all plugins and vendor bundle loaded) and is about to be mounted. This delays your layout and page components.

Pros: Safer and still provides good improvements

Cons: May still break certain layouts if they are js dependent.

Benchmark: ~70% reduction

export default {
  delayHydration: {
    mode: 'mount'
  }
}

Manual Mode

Using the manual mode, you manually specify what part of your app you'd like to delay. Useful for when you need some part of the page to always hydrate immediately, such as a navigation drawer.

Pros: Safest way to optimise

Cons: Speed improvement based on usage

export default {
  delayHydration: {
    mode: 'manual'
  }
}

DelayHydration component

Once you have set the mode, you need to use the component. It's recommended you use the component within your layout file.

<template>
<div>
    <my-header />
    <delay-hydration>
        <!-- You must have a single child node as the slot -->
        <div>
            <main>
                <nuxt />
            </main>
            <my-footer />
        </div>
    </delay-hydration>
</div>
</template>

This component is a wrapper for a pre-configured vue-lazy-hydration component.

If you're using nuxt/components then no import is required. Otherwise, you can import the component as:

import { DelayHydration } from 'nuxt-delay-hydration/dist/components'

The behaviour of the component should be controlled by the advanced configuration, however props are provided for convenience.

Props

forever: boolean:false Toggle the hydration delay to last forever

debug: boolean:false Toggle the debug logging

replayClick: boolean:false Toggle the click replay

Guides

Debugging

export default {
    delayHydration: {
        debug: process.env.NODE_ENV === 'development',
    },
}

export default {
    delayHydration: {
        forever: true
    },
}

<template>
<div>
    <my-header />
    <delay-hydration>
        <div>
            <!-- Show the hydration status, only for debugging -->
            <hydration-status />
            <main>
                <nuxt />
            </main>
            <my-footer />
        </div>
    </delay-hydration>
</div>
</template>

import { HydrationStatus } from 'nuxt-delay-hydration/dist/components'

Performance Auditing

Use my audit tool: https://unlighthouse.dev/

Replaying hydration click

export default {
    delayHydration: {
        replayClick: true
    },
}

Further Optimisations

<script>
export default {
  components: {
    AdSlider: () => import('./AdSlider.vue'),
    ArticleContent: () => import('./ArticleContent.vue'),
    CommentForm: () => import('./CommentForm.vue'),
    ImageSlider: () => import('./ImageSlider.vue'),
  },
};
</script>

Advanced Configuration

Configuration should be provided on the delayHydration key within your Nuxt config.

If you're finding the lab or field data is not performing, you may want to tinker with this advanced configuration.

Event Hydration

hydrateOnEvents

• Type: string[]
• Default: [ 'mousemove', 'scroll', 'keydown', 'click', 'touchstart', 'wheel' ]

Controls which browser events should trigger the hydration to resume. By default, it is quite aggressive to avoid possible user experience issues.

replayClick

• Type: boolean
• Default: false

If the trigger for hydration was a click, you can replay it. Replaying it will re-execute the event when it is presumed your app is hydrated.

For example, if a user clicks a hamburger icon and hydration is required to open the menu, it would replay the click once hydrated.

⚠️ This is experimental, use with caution.

replayClickMaxEventAge

• Type: number (milliseconds)
• Default: 1000

The replay click event will not run if the hydration takes more than the limit specified.

This limit is designed to avoid possible user experience issues.

Idle Hydration

idleCallbackTimeout

• Type: number (milliseconds)
• Default: 7000

When waiting for an idle callback, it's possible to define a max amount of time to wait in milliseconds. This is useful when there are a lot of network requests happening.

postIdleTimeout

• Type: { mobile: number, desktop: number } (milliseconds)
• Default: { mobile: 6000, desktop: 5000, }

How many to wait (in milliseconds) after the idle callback before we resume the hydration. This extra timeout is required to avoid the standard "blocking", we need to provide real idle time to lighthouse.

Mobile should always be higher than desktop as the CPU capacity will generally be a lot less than a desktop.

Note: The default will likely be customised in the future based on further benchmarking.

Debugging

debug

• Type: boolean
• Default: false

Log details in the console on when hydration is blocked and when and why it becomes unblocked.

forever

• Type: boolean
• Default: false

Run the delay forever, useful for testing your app in a non-hydrated state.

Benchmarks

• Pokemon
• Countries
• Manual

Live examples

• https://www.odysseytraveller.com/
• https://massivemonster.co/

Credits

• Markus Oberlehner. Pioneer of the lazy hydration in Vue

Sponsors

License

MIT License © 2022 - Present Harlan Wilton