Nuxt Partial Hydrate

[!WARNING]
This module is currently under development and not yet ready for production use.

A Nuxt module that enables partial hydration for React components within Vue applications, inspired by Astro’s Islands architecture.

Usage

Basic Example

<script setup>
import { Button } from "./components/react/Button";

const handleClick = () => {
  console.log("Button clicked!");
};
</script>

<template>
  <div>
    <h1>My Nuxt App with React Components</h1>

    <!-- React component with immediate hydration -->
    <Button client:load label="Click me" :onClick="handleClick" />
  </div>
</template>

Hydration Strategies

• client:load - Hydrates immediately when the page loads
• client:idle - Hydrates when the browser is idle (using requestIdleCallback)
• client:visible - Hydrates when the component enters the viewport
• client:media="(min-width: 768px)" - Hydrates when the media query matches
• client:only - Renders only on the client (no SSR)

Advanced Example

<script setup>
import { UserCard } from "./components/react/UserCard";
import { Chart } from "./components/react/Chart";

const userData = ref({
  name: "John Doe",
  avatar: "/avatar.jpg",
});
</script>

<template>
  <div>
    <!-- Hydrate when visible -->
    <UserCard client:visible :user="userData" />

    <!-- Hydrate only on desktop -->
    <Chart client:media="(min-width: 1024px)" :data="chartData" />

    <!-- Client-only rendering -->
    <InteractiveMap client:only :markers="locations" />
  </div>
</template>

Configuration

Configure the module in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["nuxt-partial-hydrate"],

  partialHydrate: {
    // React version (default: 18)
    reactVersion: 18,

    // Enable SSR for React components (default: true)
    ssr: true,

    // Debug mode (default: false)
    debug: false,
  },
});

How It Works

1. undefinedBuild Time: The module transforms Vue SFC files to detect React components with client:* directives
2. undefinedServer Side: React components are rendered to HTML using ReactDOMServer
3. undefinedClient Side: Components are hydrated based on their specified strategy
4. undefinedRuntime: React and Vue coexist, with React components managed by the wrapper

TypeScript Support

The module provides full TypeScript support. React component props are properly typed in Vue templates.

// components/react/Button.tsx
interface ButtonProps {
  label: string;
  onClick?: () => void;
  variant?: "primary" | "secondary";
}

export const Button: React.FC<ButtonProps> = ({ label, onClick, variant }) => {
  // Component implementation
};

Contribution

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

License

MIT