Nuxt Delay Hydration

Improve your Nuxt.js Google Lighthouse score by delaying hydration ⚡️

Features

• 🚀 Performance Boost - Significantly improve your Lighthouse performance score
• 🎯 Smart Hydration - Multiple hydration strategies (init, mount, manual)
• 📱 Device Aware - Different timeout settings for mobile and desktop
• 🎮 Event Driven - Trigger hydration on user interactions
• 🔄 Event Replay - Replay user interactions after hydration
• 🐛 Debug Mode - Built-in debugging for development
• 🔧 Highly Configurable - Fine-tune every aspect of the delay behavior

Quick Setup

1. Add nuxt-optimization-plugin dependency to your project

# Using npm
npm install nuxt-optimization-plugin

# Using yarn
yarn add nuxt-optimization-plugin

# Using pnpm
pnpm add nuxt-optimization-plugin

2. Add nuxt-optimization-plugin to the modules section of nuxt.config.ts

export default defineNuxtConfig({
    modules: ["nuxt-optimization-plugin"],
    delayHydration: {
        // Enable delay hydration
        mode: "init",
    },
});

That's it! You can now use Nuxt Delay Hydration in your Nuxt app ✨

Configuration

Hydration Modes

• init - Delay hydration until after the app initialization
• mount - Delay hydration until after the app mount
• manual - Completely manual hydration control
• false - Disable the module (default)

Configuration Options

export default defineNuxtConfig({
    delayHydration: {
        // Hydration mode
        mode: "init", // 'init' | 'mount' | 'manual' | false

        // Events that trigger hydration
        hydrateOnEvents: [
            "mousemove",
            "scroll",
            "keydown",
            "click",
            "touchstart",
            "wheel",
        ],

        // Idle callback timeout (ms)
        idleCallbackTimeout: 7000,

        // Post-idle timeout by device type
        postIdleTimeout: {
            mobile: 6000,
            desktop: 5000,
        },

        // Replay user interactions after hydration
        replayClick: false,

        // Max age for replaying events (ms)
        replayClickMaxEventAge: 1000,

        // Enable debug logging
        debug: false,

        // Never hydrate (for testing)
        forever: false,
    },
});

Usage Examples

Basic Setup

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ["nuxt-optimization-plugin"],
    delayHydration: {
        mode: "init",
        debug: true, // Enable for development
    },
});

Advanced Configuration

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ["nuxt-optimization-plugin"],
    delayHydration: {
        mode: "mount",
        hydrateOnEvents: ["click", "touchstart"], // Only on user interaction
        postIdleTimeout: {
            mobile: 8000, // Longer delay on mobile
            desktop: 4000,
        },
        replayClick: true, // Replay user clicks
        debug: process.env.NODE_ENV === "development",
    },
});

Manual Hydration

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ["nuxt-optimization-plugin"],
    delayHydration: {
        mode: "manual",
    },
});

<!-- In your component -->
<template>
    <div>
        <button @click="triggerHydration">Load Interactive Content</button>
    </div>
</template>

<script setup>
const triggerHydration = () => {
    // Manually trigger hydration
    if (process.client && window.$delayHydration) {
        window.$delayHydration.hydrate();
    }
};
</script>

How It Works

This module delays the hydration process of your Nuxt.js application, which can significantly improve your initial page load performance and Lighthouse scores. Here's what happens:

1. Initial Load: The page loads with static HTML/CSS, providing immediate visual feedback
2. Delayed Hydration: JavaScript hydration is delayed based on your chosen strategy
3. Smart Triggering: Hydration occurs when users interact with the page or after specified timeouts
4. Event Replay: User interactions can be replayed after hydration completes

Performance Benefits

• ⚡ Faster First Contentful Paint (FCP)
• 🎯 Improved Largest Contentful Paint (LCP)
• 📊 Better Lighthouse Performance Score
• 🚀 Reduced Time to Interactive (TTI)
• 📱 Enhanced Mobile Performance

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm run stub

# Develop with the playground
pnpm run dev

# Build the module
pnpm run build

# Run ESLint
pnpm run lint

# Run tests
pnpm run test

Contributing

Contributions are welcome! Please read the contributing guidelines first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License

Credits

Made with ❤️ by Harlan Wilton