mandu-hydration

Files (1)

• SKILL.md

SKILL.md (first lines)

# Mandu Island Hydration

Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티브하게 만드는 기술입니다.

## Import Rule (CRITICAL)

Client islands MUST import from `@mandujs/core/client`, NOT `@mandujs/core`.
The main module includes server-side dependencies that break client bundles.

```typescript
// CORRECT
import { island } from "@mandujs/core/client";
import { useServerData, useHydrated, useIslandEvent } from "@mandujs/core/client";

// WRONG - will cause build errors or bloated bundles
import { island } from "@mandujs/core";
```

## Island File Conventions

| File | Purpose |
|------|---------|
| `*.island.tsx` | Island component (auto-detected for hydration) |
| `*.client.tsx` | Client-only logic file |
| `*.slot.ts` / `*.slot.tsx` | Server-side data loader |

All island files MUST have `"use client"` directive at the very top.

## island() API

`island()` takes a single definition object. Do not call
`island("visible", Component)`; that is not a supported runtime API.

### Simple component wrapper

```tsx
// app/counter.island.tsx
"use client";

import { wrapComponent } from "@mandujs/core/client";
import { useState } from "react";

function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

export default wrapComponent(Counter);
```

### Client Island with Setup (advanced)

```tsx
// app/chat.island.tsx
"use client";

import { island } from "@mandujs/core/client";
import { useState } from "react";

export default island<ServerData>({
  setup(data) {
    const [messages, setMessages] = useState(data.initialMessages);
    return { messages, setMessages };
  },
  render({ messages, setMessages }) {
    return <div>{messages.map(m => <p key={m.id}>{m.text}</p>)}</div>;
  }
});
```

Islands are page-level client bundles. They are discovered from route/client
modules and rendered by the framework wrapper, not embedded as inline JSX. If
you need an interactive region inside a server page, use `partial()` and render
its `.Render` component.

```tsx
"use client";

import { partial } from "@mandujs/core/client";

const CounterPartial = partial({
  component: Counter,
  priority: "visible",
});

export function Header() {
  return <CounterPartial.Render initialCount={0} />;
}
```

## Hydration Priorities

| Priority | When loaded | Use case |
|----------|------------|----------|
| `"immediate"` | Page load | Critical interactions (nav, auth) |
| `"visible"` | In viewport | Default - most components |
| `"idle"` | Browser idle | Below-fold content |
| `"interaction"` | User interacts | Heavy widgets (editor, map) |

```tsx
// app/page.tsx or manifest route config
export const hydration = {
  strategy: "island",
  priority: "visible",
  preload: false,
};

// Inline client regions use partial({ priority }).
partial({ component: CommentSection, priority: "visible" });
```

## Client Hooks

```typescript
import { useServerData, useHydrated, useIslandEvent } from "@mandujs/core/client";

// Access data from server slot
const data = useServerData<UserData>("user", defaultValue);

From konamgil/mandu, MPL-2.0.

More from konamgil/mandu