# Connect a Next.js application

Add a same-origin backend bridge and reuse the React SDK without a second agent state model.

## Install the framework layer

```bash
npm install "https://wkala.okal.io/downloads/wkala-client-0.1.0.tgz" "https://wkala.okal.io/downloads/wkala-react-0.1.0.tgz" "https://wkala.okal.io/downloads/wkala-next-0.1.0.tgz"
```

Use Next.js 16 and React 19. The browser entry reexports `AgentProvider`, `useAgent`, `useSession`, and `AgentClient` from the React layer. The `/server` entry enforces Next's server-only boundary.

## Add the customer backend proxy

```typescript
// app/app/[...path]/route.ts
import { createAppProxy } from "@wkala/next/server"

export const runtime = "nodejs"
export const dynamic = "force-dynamic"

const route = createAppProxy({
  target: () => process.env.RELAY_CUSTOMER_URL!,
})
export { route as GET, route as POST, route as PATCH, route as DELETE }
```

`RELAY_CUSTOMER_URL` is a fixed server environment variable pointing to your Python application origin, such as `http://127.0.0.1:8081`. This compatibility name is intentionally retained. Do not prefix it with `NEXT_PUBLIC_`. It has no path, credentials, query, or fragment. A browser cannot choose its destination.

Your Python application owns its end-user sign-in, session ownership, Origin and CSRF checks, and the private Wkala key. Set its allowed browser origin to your public Next.js URL. Set its cookie path to `/app`. Use Secure cookies behind HTTPS. This layer is independent from the Wkala service dashboard's login.

## Render the same React integration

```tsx
"use client"
import { AgentClient, AgentProvider, useSession } from "@wkala/next"
```

Follow the [React guide](/docs/raw/react?locale=en). No service key belongs in a component prop. Keep landing and documentation pages static. Only authenticated application views need request-specific behavior.

## Optional authenticated server snapshot

```typescript
// In a Server Component, using an already authorized session ID.
import { cookies } from "next/headers"
import { getSessionSnapshot } from "@wkala/next/server"

const snapshot = await getSessionSnapshot({
  target: process.env.RELAY_CUSTOMER_URL!,
  sessionId: ownedSessionId,
  cookie: (await cookies()).toString(),
})
```

The customer backend still checks ownership. This request is no-store. Pass the exact result to `useSession(id, { initialSnapshot: snapshot })` for coherent hydration. Create request-scoped stores. Do not cache private snapshots across users.

## Stream without buffering

The proxy forwards status and headers, then the response body with backpressure. The connection deadline ends after headers. Disconnection cancels observation without issuing an execution cancellation. Configure any reverse proxy to disable SSE buffering and support long-lived connections.

Only the customer application route allowlist is forwarded. Browser Authorization and arbitrary trusted-subject headers are not propagated. The proxy never accepts a Wkala machine key. Operator, provider, skill, and MCP management remain backend-only.

The kit's `/dashboard/playground` route is the complete customer-backend demo. `/dashboard` and `/console` operate the Wkala service itself.
