# CopilotKit Provider Setup (React)

Mount `CopilotKitProvider` once near the root of the React tree. Every
CopilotKit hook (`useAgent`, `useFrontendTool`, `useRenderTool`, etc.) and
every chat component (`CopilotChat`, `CopilotPopup`, `CopilotSidebar`) must
be rendered inside this provider.

All v2 imports use the `@copilotkit/react-core/v2` subpath. Imports from the
package root are v1 and will not work with v2 hooks or components.

## Setup

### Next.js App Router (and any RSC-based framework)

`@copilotkit/react-core/v2` is marked `"use client"`. You must mount the
provider from a client component, not a server component. The cleanest
pattern is a dedicated client-only `providers.tsx`.

```tsx
// app/providers.tsx
"use client";

import { CopilotKitProvider } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider
      runtimeUrl="/api/copilotkit"
      credentials="include"
      onError={({ code, error, context }) => {
        console.error("[copilotkit]", code, error, context);
      }}
    >
      {children}
    </CopilotKitProvider>
  );
}
```

For auth headers that change over the session (rotating bearer tokens,
refreshed cookies), see the "Stable headers for rotating auth tokens"
pattern below. Avoid putting a `useMemo(() => ({ Authorization: ... }),
[])` on the provider — an empty deps array captures the token at mount
and never refreshes.

```tsx
// app/layout.tsx — server component
import { Providers } from "./providers";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

### Vite / React Router v7 / SPA

```tsx
import { CopilotKitProvider } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export function App({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      {children}
    </CopilotKitProvider>
  );
}
```

### SPA with CopilotKit Cloud (no self-hosted runtime)

```tsx
<CopilotKitProvider publicApiKey="ck_pub_..." />
```

`publicApiKey` is the canonical prop for running CopilotKit from a pure
client bundle. `publicLicenseKey` is an alias that resolves to the same
value (`publicApiKey ?? publicLicenseKey`) — accept in old code, but
always write `publicApiKey` in new code.

## Core Patterns

### Stable headers for rotating auth tokens

For tokens that change during the session, use the imperative setter instead
of re-rendering the provider with a new `headers` prop.

```tsx
"use client";
import { useCopilotKit } from "@copilotkit/react-core/v2";
import { useEffect } from "react";

export function AuthTokenSync({ token }: { token: string }) {
  const { copilotkit } = useCopilotKit();
  useEffect(() => {
    copilotkit.setHeaders({ Authorization: `Bearer ${token}` });
  }, [copilotkit, token]);
  return null;
}
```

### Global error handler

`onError` fires for every `CopilotKitCoreErrorCode` emitted by core. Keeps
UI from getting stuck in "connecting..." when the runtime URL is wrong or
CORS is misconfigured.

```tsx
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  onError={({ code, error, context }) => {
    telemetry.capture({ code, message: error.message, context });
  }}
/>
```

### Sharing app properties with every run

`properties` flows to the runtime on each agent run — useful for tenant IDs,
feature flags, or anything the server needs.

```tsx
const properties = useMemo(
  () => ({ tenantId: user.tenantId, locale: user.locale }),
  [user.tenantId, user.locale],
);

<CopilotKitProvider runtimeUrl="/api/copilotkit" properties={properties} />;
```

## Common Mistakes

### CRITICAL — Mounting the provider from a Server Component

Wrong:

```tsx
// app/page.tsx (server component — no "use client")
import { CopilotKitProvider } from "@copilotkit/react-core/v2";

export default function Page() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">...</CopilotKitProvider>
  );
}
```

Correct:

```tsx
// app/providers.tsx
"use client";
import { CopilotKitProvider } from "@copilotkit/react-core/v2";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      {children}
    </CopilotKitProvider>
  );
}

// app/layout.tsx imports <Providers>.
```

`@copilotkit/react-core/v2` begins with `"use client"`. Importing it from a
server component silently strips interactivity — the provider renders but
none of the hooks wire up.

Source: `packages/react-core/src/v2/index.ts:1`

### CRITICAL — Using `agents__unsafe_dev_only` or `selfManagedAgents` in production

Wrong:

```tsx
<CopilotKitProvider
  agents__unsafe_dev_only={{
    default: new BuiltInAgent({ apiKey: process.env.OPENAI_KEY! }),
  }}
/>
// or the alias (same thing):
<CopilotKitProvider
  selfManagedAgents={{ default: new BuiltInAgent({ apiKey: "..." }) }}
/>
```

Correct:

```tsx
// Route through a runtime that keeps secrets server-side:
<CopilotKitProvider runtimeUrl="/api/copilotkit" />

// Or for a pure SPA, use CopilotKit Cloud:
<CopilotKitProvider publicApiKey="ck_pub_..." />
```

Both props are aliases for the same dev-only mechanism and ship any embedded
credentials to the browser bundle. Never use either for production agents.

Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:136-138,393`

### HIGH — Inline object props rebuilt every render

Wrong:

```tsx
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  headers={{ Authorization: `Bearer ${token}` }}
  properties={{ tenantId: user.tenantId }}
/>
```

Correct:

```tsx
const headers = useMemo(() => ({ Authorization: `Bearer ${token}` }), [token]);
const properties = useMemo(
  () => ({ tenantId: user.tenantId }),
  [user.tenantId],
);

<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  headers={headers}
  properties={properties}
/>;
```

New object identity on every render causes the provider to diff-churn
internal state and may thrash tool/renderer registration. `useStableArrayProp`
also logs a `console.error` when array-prop shape changes without
memoization.

Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:324-340,399-410`

### HIGH — Missing `onError` leaves users stuck in "connecting..."

Wrong:

```tsx
<CopilotKitProvider runtimeUrl="/api/copilotkit" />
```

Correct:

```tsx
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  onError={({ code, error, context }) => {
    telemetry.capture({ code, error, context });
  }}
/>
```

Without `onError`, connection failures (bad runtime URL, CORS, network) keep
the provider in a provisional state with `ProxiedCopilotRuntimeAgent`
instances that never resolve. The chat UI keeps showing "connecting..."
forever and users never see the actual error.

Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:638-660`

### HIGH — Writing `publicLicenseKey` in new code

Wrong:

```tsx
<CopilotKitProvider publicLicenseKey="ck_pub_..." />
```

Correct:

```tsx
<CopilotKitProvider publicApiKey="ck_pub_..." />
```

`publicLicenseKey` still works as an alias, but `publicApiKey` is the
canonical name in v2. The provider resolves
`publicApiKey ?? publicLicenseKey`. Always write the canonical form in
new code.

Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:122-128,391`

### MEDIUM — Putting the provider below a layout that uses CopilotKit

Wrong:

```tsx
<html>
  <body>
    <Header>{/* Header uses useFrontendTool internally */}</Header>
    <CopilotKitProvider>{children}</CopilotKitProvider>
  </body>
</html>
```

Correct:

```tsx
<html>
  <body>
    <CopilotKitProvider>
      <Header />
      {children}
    </CopilotKitProvider>
  </body>
</html>
```

Any component that calls `useCopilotKit`, `useFrontendTool`, `useAgent`, or
any other CopilotKit hook must be a descendant of `CopilotKitProvider`.
Placing the provider beside or below a consumer throws at mount.

Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (context)
