# Next.js integration

> Wire Hatched into a Next.js App Router app — server components, route handlers, widgets, and webhooks.

Source: https://docs.hatched.live/docs/guides/nextjs-integration

Next.js is the most common host for Hatched integrations. The SDK is
server-only, so every call happens in a server component, a route
handler, or middleware — never in a `"use client"` component.

## 1. Install and configure

```bash
pnpm add @hatched/sdk-js
```

```bash
# .env.local
HATCHED_API_KEY=hatch_test_...
HATCHED_WEBHOOK_SECRET=whsec_...
```

## 2. Shared client

```ts
// lib/hatched.ts
import { HatchedClient } from '@hatched/sdk-js';

export const hatched = new HatchedClient({
  apiKey: process.env.HATCHED_API_KEY!,
});
```

Importing this module from a client component will fail at build time —
good, that's the point. Keep it under `lib/` or `server/` and let the
bundler prevent misuse.

## 3. Server component reads

```tsx
// app/buddy/page.tsx
import { hatched } from '@/lib/hatched';

export default async function BuddyPage({ params }: { params: { userId: string } }) {
  const buddies = await hatched.buddies.list({ userId: params.userId });
  return <BuddyList data={buddies.data} />;
}
```

## 4. Route handlers for writes

Mutations (events, coin earn/spend, widget session mint) go through route
handlers. They run on the server with access to `HATCHED_API_KEY`.

```ts
// app/api/hatched/events/route.ts
import { hatched } from '@/lib/hatched';
import { ValidationError } from '@hatched/sdk-js';

export async function POST(req: Request) {
  const { userId, lessonId, score } = await req.json();
  try {
    const effects = await hatched.events.send({
      eventId: `lesson_${lessonId}_${userId}`,
      userId,
      type: 'lesson_completed',
      properties: { lessonId, score },
    });
    return Response.json(effects);
  } catch (err) {
    if (err instanceof ValidationError) {
      return Response.json({ error: err.details }, { status: 422 });
    }
    throw err;
  }
}
```

## 5. Widget session mint endpoint

Your browser widget calls this to get a short-lived token. Never expose
your secret API key directly.

```ts
// app/api/hatched/session/route.ts
import { hatched } from '@/lib/hatched';
import { getServerSession } from '@/lib/auth';

export async function POST() {
  const user = await getServerSession();
  if (!user) return new Response('unauthorized', { status: 401 });

  const session = await hatched.widgetSessions.create({
    buddyId: user.buddyId,
    userId: user.id,
    scopes: ['read', 'events:track', 'marketplace:browse'],
    ttlSeconds: 60 * 15,
  });
  return Response.json({ token: session.token, expiresAt: session.expiresAt });
}
```

```tsx
// components/buddy-widget.tsx
'use client';
import { useEffect, useRef, useState } from 'react';

export function BuddyWidget() {
  const [token, setToken] = useState<string | null>(null);
  const mountRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    fetch('/api/hatched/session', { method: 'POST' })
      .then((r) => r.json())
      .then(({ token }) => setToken(token));
  }, []);

  useEffect(() => {
    if (token) (window as any).__HATCHED_WIDGET__?.init({ token });
  }, [token]);

  if (!token) return null;
  return (
    <>
      <script src="https://cdn.hatched.live/widget.js" data-session-token={token} defer />
      <div ref={mountRef} data-hatched-mount="buddy" />
    </>
  );
}
```

## 6. Webhook handler

Raw body is critical for signature verification. In the App Router,
`req.text()` preserves the raw bytes.

```ts
// app/api/hatched/webhooks/route.ts
import { WebhooksResource } from '@hatched/sdk-js';

export const runtime = 'nodejs'; // `verifySignature` uses node:crypto

export async function POST(req: Request) {
  const raw = await req.text();
  const signature = req.headers.get('hatched-signature') ?? '';

  const valid = WebhooksResource.verifySignature(
    raw,
    signature,
    process.env.HATCHED_WEBHOOK_SECRET!,
  );
  if (!valid) return new Response('invalid signature', { status: 400 });

  const event = JSON.parse(raw);
  // enqueue for background processing
  await handle(event);

  return new Response(null, { status: 202 });
}
```

## 7. Middleware gotcha

Next.js Middleware runs in the Edge runtime. `@hatched/sdk-js` works in
Edge **only** with `publishableKey` (read endpoints). For secret-key
writes, move the logic into a `runtime = 'nodejs'` route handler.

## Project layout recap

```
app/
  api/
    hatched/
      events/route.ts        POST — ingest an event
      session/route.ts       POST — mint widget session token
      webhooks/route.ts      POST — receive webhook (runtime=nodejs)
  buddy/page.tsx             server component using hatched.buddies.*
components/
  buddy-widget.tsx           "use client" — mounts data-hatched-mount="buddy"
lib/
  hatched.ts                 shared HatchedClient instance
```