Status: Stable v2 v0 β , v3 main β Made possible by my Sponsor Program π Follow me @harlan_zw π¦ |
β οΈ This is a "hack" to trick Google Lighthouse into thinking your site is faster than it otherwise would be.
If you're using Nuxt 2.x, please follow the docs on the v0 branch. β οΈ Nuxt 2 is deprecated and won't receive support.
npx nuxi@latest module add delay-hydration
Requirement: Progressively enhanced SSR or SSG Nuxt app.
// nuxt.config.ts
export default {
modules: [
'nuxt-delay-hydration',
],
delayHydration: {
// enables nuxt-delay-hydration in dev mode for testing
// NOTE: you should disable this once you've finished testing, it will break HMR
debug: process.env.NODE_ENV === 'development'
}
}
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 all scripts from loading. | Zero or minimal plugins/modules. |
mount recommended | Delays Nuxt while it's 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. |
All other apps |
Regardless of the mode you choose, please read further optimisations.
This mode delays all scripts from loading until the hydration promise is resolved.
It does this by hooking into the HTML rendering, removing all script tags and adding them back after the hydration promise is resolved.
This will provide the biggest speed improvements however is the riskiest.
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'
}
}
This mode delays Nuxt while it's mounting. Plugins and some third-party scripts will work.
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.
<template>
<div>
<DelayHydration>
<div>
<LazyMyExpensiveComponent />
</div>
</DelayHydration>
</div>
</template>
You can configure the module on a per-page basis using route rules.
// nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
// delay the home page
'/': { delayHydration: 'mount' },
// disable the module for the admin
'/admin/': { delayHydration: false }
}
})
You can also define them are your page-level using defineRouteRules.
Use my audit tool: https://unlighthouse.dev/
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.
Note: It's recommended to use route rules instead of these filtering options.
Using the include
and exclude
options, you can specify which routes you'd like to delay hydration on.
// nuxt.config.ts
export default defineNuxtConfig({
delayHydration: {
include: [
'/blog/**',
],
exclude: [
'/admin/**'
],
},
})
You can provide a glob pattern similar to route rules or a regex.
hydrateOnEvents
string[]
[ '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
boolean
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.
idleCallbackTimeout
number
(milliseconds)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
{ mobile: number, desktop: number }
(milliseconds){ mobile: 5000, desktop: 4000, }
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
boolean
false
Log details in the console on when hydration is blocked and when and why it becomes unblocked.
Live examples
MIT License Β© 2022 - Present Harlan Wilton