Improve your Nuxt.js Google Lighthouse score by delaying hydration ⚡️
- ⚡️ 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
Motivation
Hydration is the process of hooking up static HTML with your Nuxt app to provide reactivity, used in SSR and SSG.
This hydration process is expensive, especially with Nuxt 2. Google Lighthouse penalises hydration with a high "Total Blocking Time" and "Time to Interactive".
While this is unavoidable in most apps, for static sites which depend on minimal interactivity, it is possible and safe to delay the hydration to avoid this penalty.
The current solution for delaying hydration is vue-lazy-hydration which works well. However, it can require a lot of tinkering, may break your HMR and not solve the performance issues.
In mount and init mode, this module delays Nuxt core code to squeeze out maximum performance, specifically around large payload executions.
Nuxt Delay Hydration aims to provide optimisations with minimal tinkering, by making certain assumptions on trade-offs. This module isn't built to replace vue-lazy-hydration, but as an abstraction layer on top of it.
How this module works
A promise is injected into your app, the location is based on the mode. The promise is resolved as soon as either of these events has fired:
- an interaction event (mouse move, scroll, click, etc)
- an idle callback with a fixed timeout
The idle CPU time hints to Google that these scripts are not required for your app to run.
For example:
- if a Google bot visits the page and has no interaction, out of the box the hydration won't occur until the browser idle callback + 6 seconds
- if a user visits the page and moves their cursor or scrolls, the hydration will be triggered immediately. The chance of interacting with the non-hydration app will be minimised
Keep in mind, this is a hacky solution. Until Google can recognise which scripts are truly blocking, we'll need to rely on this approach.
yarn add nuxt-delay-hydration
# npm i nuxt-delay-hydrationRequirement: SSR, full-static (SSG) is highly recommended.
Further Requirements
Your scripts should not be required to use your website, this is what we're hinting to Google.
To do that you can ensure:
- Full HTML served on the initial response
- Scripts don't trigger a CLS
- Scripts shouldn't be required for a user to interact with your site
- Avoid using scripts to set images, will affect the LCP
Please benchmark your app before starting.
This module has been tested on documentation sites, blogs and misc content sites.
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.
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
| Type | Description | Use Case |
|---|---|---|
false default |
Disable the module | Testing |
| init | Delays Nuxt app creation. All code is delayed including plugins and third-party scripts. | Zero or minimal plugins/modules. |
| mount recommended | Delays Nuxt after creation and before mounting. Plugins and some third-party scripts will work. | Minimal non-critical plugins and third-party plugins. |
| manual | Delay is provided by the DelayHydration component. Extends vue-lazy-hydration |
All other apps |
Regardless of the mode you choose, please read further optimisations.
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'
}
}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'
}
}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'
}
}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
Debug mode
It's recommended that you do thorough testing on your app with the module before deploying it into production.
To make sure the module is doing what you expect, there is a debug mode, which when enabled will log behaviour in the console.
It might be a good idea to always debug on your local environment, in that instance you could do:
export default {
delayHydration: {
debug: process.env.NODE_ENV === 'development',
},
}Delay hydration forever
Since the hydration will trigger instantly when you interact with the page, it can be useful to manually delay the hydration forever so you can test the functionality of your app in its non-hydrated state.
export default {
delayHydration: {
forever: true
},
}Visualising the hydration status
It can be unclear at times whether your app has been hydrated or not if it's quite static, this can make debugging hard.
To make things easier, there is a component HydrationStatus which will tell you what's going on.
<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>If you're using nuxt/components then no import is required. Otherwise, you can import the component as:
import { HydrationStatus } from 'nuxt-delay-hydration/dist/components'How to audit your app
It's important to measure the performance changes in this module and any configuration changes you make.
The simplest way to benchmark is to use the Google Lighthouse tool within Google Chrome.
However, due to unpredictable results, it's recommended to run numerous iterations of the audit. To make that easier this module provides a script to run a performance audit with 10 iterations:
- Install dependencies:
yarn add -D lighthouse chrome-launcher - Build and start your Nuxt app
nuxt generate && nuxt start - Run the audit script
node ./node_modules/nuxt-delay-hydration/scripts/audit.js
What is this and how to enable
One of the issues with delaying hydration is that a user interaction event can occur before your scripts are loaded, leading to a user having to click on something multiple times for it to do what they expect. Think of a hamburger that is triggered using Javascript, if your app isn't hydrated then clicking it won't do anything.
The best fix for this is to write your HTML in a way that doesn't need Javascript to be interactive.
However, there are use cases where you need to use Javascript and responding to the first click is important. In those instances, you can enable the replay of the click.
export default {
delayHydration: {
replayClick: true
},
}This is an experimental configuration, you should test this option yourself before implementing it into your production app.
Load heavy components async
When you load in a heavy component synchronously, the javascript will be bundled in with the main application payload.
This will decrease all of your performance metrics. It's recommended you use async imports for these components.
Analyze your components and load the big ones async. If you're using nuxt/components, you can
easily prefix them with Lazy to do so, otherwise, you can use the following syntax.
<script>
export default {
components: {
AdSlider: () => import('./AdSlider.vue'),
ArticleContent: () => import('./ArticleContent.vue'),
CommentForm: () => import('./CommentForm.vue'),
ImageSlider: () => import('./ImageSlider.vue'),
},
};
</script>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.
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.
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.
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.
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.
Live examples
- Markus Oberlehner. Pioneer of the lazy hydration in Vue
MIT License © 2021 Harlan Wilton