@custom-react-hooks/use-island

useIsland

A React hook for implementing island architecture with selective hydration, allowing you to optimize performance by hydrating components only when needed.

Features

• 🏝️ Island Architecture: Implement selective hydration patterns
• ⚡ Performance Optimized: Hydrate components only when necessary
• 🎯 Priority Support: Control hydration priority (high, normal, low)
• 👁️ Visibility Detection: Automatic hydration based on visibility
• 🔄 Lazy Loading: Support for lazy hydration
• 📊 State Management: Track hydration and visibility states
• 🎣 Callbacks: Custom handlers for hydration events
• 🧹 Auto Cleanup: Automatic cleanup on unmount

Installation

npm install @custom-react-hooks/use-island

Usage

Basic Usage

import React from 'react';
import { useIsland } from '@custom-react-hooks/use-island';

function MyIslandComponent() {
  const { isHydrated, isVisible, hydrate, dehydrate } = useIsland('my-island');

  return (
    <div>
      <p>Hydrated: {isHydrated ? 'Yes' : 'No'}</p>
      <p>Visible: {isVisible ? 'Yes' : 'No'}</p>
      <button onClick={hydrate}>Hydrate</button>
      <button onClick={dehydrate}>Dehydrate</button>
    </div>
  );
}

With Priority

import React from 'react';
import { useIsland } from '@custom-react-hooks/use-island';

function HighPriorityIsland() {
  const { isHydrated, hydrate } = useIsland('critical-island', {
    priority: 'high',
    lazy: false
  });

  return (
    <div>
      {isHydrated ? (
        <ExpensiveComponent />
      ) : (
        <div>Loading...</div>
      )}
    </div>
  );
}

With Callbacks

import React from 'react';
import { useIsland } from '@custom-react-hooks/use-island';

function CallbackIsland() {
  const { isHydrated, hydrate } = useIsland('callback-island', {
    onHydrate: (islandId) => {
      console.log(`Island ${islandId} hydrated`);
      // Analytics, logging, etc.
    },
    onDehydrate: (islandId) => {
      console.log(`Island ${islandId} dehydrated`);
    }
  });

  return (
    <div>
      <button onClick={hydrate}>
        {isHydrated ? 'Hydrated' : 'Hydrate Island'}
      </button>
    </div>
  );
}

Lazy Hydration

import React from 'react';
import { useIsland } from '@custom-react-hooks/use-island';

function LazyIsland() {
  const { isHydrated, isVisible } = useIsland('lazy-island', {
    lazy: true,
    priority: 'low'
  });

  return (
    <div>
      {isHydrated ? (
        <HeavyComponent />
      ) : (
        <PlaceholderComponent />
      )}
    </div>
  );
}

API Reference

Parameters

• islandId (string): Unique identifier for the island
• options (IslandOptions, optional): Configuration options

IslandOptions

interface IslandOptions {
  priority?: 'high' | 'normal' | 'low';
  lazy?: boolean;
  onHydrate?: (islandId: string) => void;
  onDehydrate?: (islandId: string) => void;
}

Return Value

interface IslandState {
  isHydrated: boolean;
  isVisible: boolean;
  hydrate: () => void;
  dehydrate: () => void;
}

Properties

• isHydrated (boolean): Whether the island is currently hydrated
• isVisible (boolean): Whether the island is visible in viewport
• hydrate (function): Function to hydrate the island
• dehydrate (function): Function to dehydrate the island

Use Cases

• Performance Optimization: Defer hydration of non-critical components
• Progressive Enhancement: Gradually enhance static content
• Lazy Loading: Hydrate components when they become visible
• Resource Management: Control when expensive components are active
• Server-Side Rendering: Optimize SSR with selective hydration
• Mobile Optimization: Reduce initial bundle size and improve performance

TypeScript Support

This hook is written in TypeScript and provides full type safety:

import { useIsland, IslandOptions, IslandState } from '@custom-react-hooks/use-island';

const options: IslandOptions = {
  priority: 'high',
  lazy: false
};

const island: IslandState = useIsland('my-island', options);

License

MIT © Bane Grozdanovic