# CopilotKit Provider Setup (React)
Mount the `CopilotKit` provider (from `@copilotkit/react-core/v2`) 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.
> **Which provider component?** Always use `CopilotKit` imported from `@copilotkit/react-core/v2`. It is the compatibility bridge across v1 and v2 and a strict superset of the other provider APIs. Do **not** use `CopilotKit` from the package root (`@copilotkit/react-core`, legacy v1) or `CopilotKitProvider` from `/v2` (a subset of the functionality).
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 { CopilotKit } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";
export function Providers({ children }: { children: React.ReactNode }) {
return (
{
console.error("[copilotkit]", code, error, context);
}}
>
{children}
);
}
```
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 (
{children}
);
}
```
### Vite / React Router v7 / SPA
```tsx
import { CopilotKit } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";
export function App({ children }: { children: React.ReactNode }) {
return {children};
}
```
### SPA with CopilotKit Intelligence (no self-hosted runtime)
```tsx
```
`publicLicenseKey` is the canonical prop for running CopilotKit from a
pure client bundle. `publicApiKey` is a deprecated alias that resolves to
the same value — accept it in old code, but always write
`publicLicenseKey` 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
{
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],
);
;
```
## Common Mistakes
### CRITICAL — Mounting the provider from a Server Component
Wrong:
```tsx
// app/page.tsx (server component — no "use client")
import { CopilotKit } from "@copilotkit/react-core/v2";
export default function Page() {
return ...;
}
```
Correct:
```tsx
// app/providers.tsx
"use client";
import { CopilotKit } from "@copilotkit/react-core/v2";
export function Providers({ children }: { children: React.ReactNode }) {
return {children};
}
// app/layout.tsx imports .
```
`@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
// or the alias (same thing):
```
Correct:
```tsx
// Route through a runtime that keeps secrets server-side:
// Or for a pure SPA, use CopilotKit Intelligence:
```
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
```
Correct:
```tsx
const headers = useMemo(() => ({ Authorization: `Bearer ${token}` }), [token]);
const properties = useMemo(
() => ({ tenantId: user.tenantId }),
[user.tenantId],
);
;
```
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
```
Correct:
```tsx
{
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 `publicApiKey` in new code
Wrong:
```tsx
```
Correct:
```tsx
```
`publicApiKey` still works as a deprecated alias, but `publicLicenseKey`
is the canonical name. The `CopilotKit` provider resolves
`publicLicenseKey || publicApiKey`. Always write the canonical form in
new code.
Source: `packages/react-core/src/components/copilot-provider/copilotkit.tsx:172`
### MEDIUM — Putting the provider below a layout that uses CopilotKit
Wrong:
```tsx
{/* Header uses useFrontendTool internally */}
{children}
```
Correct:
```tsx
{children}
```
Any component that calls `useCopilotKit`, `useFrontendTool`, `useAgent`, or
any other CopilotKit hook must be a descendant of the `CopilotKit`
provider. Placing the provider beside or below a consumer throws at mount.
Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (context)