Initial commit

Co-authored-by: Katia Gil Guzman <katia@openai.com>
Co-authored-by: Corwin <corwin@openai.com>

.env.example

@@ -0,0 +1,2 @@
+OPENAI_API_KEY=sk-proj-...
+NEXT_PUBLIC_CHATKIT_WORKFLOW_ID=wf_...

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  build:
+    name: Install, Lint, and Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run ESLint
+        run: npm run lint
+  

.gitignore

@@ -0,0 +1,42 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,60 @@
+# ChatKit Starter Template
+
+This repository is the simplest way to bootstrap a [ChatKit](http://openai.github.io/chatkit-js/) application. It ships with a minimal Next.js UI, the ChatKit web component, and a ready-to-use session endpoint so you can experiment with OpenAI-hosted workflows built using [Agent Builder](https://platform.openai.com/agent-builder).
+
+## What You Get
+
+- Next.js app with `<openai-chatkit>` web component and theming controls
+- API endpoint for creating a session at [`app/api/create-session/route.ts`](app/api/create-session/route.ts)
+- Quick examples for starter prompts, placeholder text, and greating message
+
+## Getting Started
+
+Follow every step below to run the app locally and configure it for your preferred backend.
+
+### 1. Install dependencies
+
+```bash
+npm install
+```
+
+### 2. Create your environment file
+
+Copy the example file and fill in the required values:
+
+```bash
+cp .env.example .env.local
+```
+
+### 3. Configure ChatKit credentials
+
+Update `.env.local` with the variables that match your setup.
+
+- `OPENAI_API_KEY` — API key with access to ChatKit.
+- `NEXT_PUBLIC_CHATKIT_WORKFLOW_ID` — the workflow you created in the ChatKit dashboard.
+- (optional) `CHATKIT_API_BASE` - customizable base URL for the ChatKit API endpoint
+
+### 4. Run the app
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:3000` and start chatting. Use the prompts on the start screen to verify your workflow connection, then customize the UI or prompt list in [`lib/config.ts`](lib/config.ts) and [`components/ChatKitPanel.tsx`](components/ChatKitPanel.tsx).
+
+### 5. Build for production (optional)
+
+```bash
+npm run build
+npm start
+```
+
+## Customization Tips
+
+- Adjust starter prompts, greeting text, and placeholder copy in [`lib/config.ts`](lib/config.ts).
+- Update the theme defaults or event handlers inside[`components/ChatKitPanel.tsx`](components/ChatKitPanel.tsx) to integrate with your product analytics or storage.
+
+## References
+
+- [ChatKit JavaScript Library](http://openai.github.io/chatkit-js/)
+- [Advanced Self-Hosting Examples](https://github.com/openai/openai-chatkit-advanced-samples)

app/App.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { useCallback } from "react";
+import { ChatKitPanel, type FactAction } from "@/components/ChatKitPanel";
+import { useColorScheme } from "@/hooks/useColorScheme";
+
+export default function App() {
+  const { scheme, setScheme } = useColorScheme();
+
+  const handleWidgetAction = useCallback(async (action: FactAction) => {
+    if (process.env.NODE_ENV !== "production") {
+      console.info("[ChatKitPanel] widget action", action);
+    }
+  }, []);
+
+  const handleResponseEnd = useCallback(() => {
+    if (process.env.NODE_ENV !== "production") {
+      console.debug("[ChatKitPanel] response end");
+    }
+  }, []);
+
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center bg-slate-100 px-6 py-6 dark:bg-slate-950">
+      <div className="mx-auto w-full max-w-5xl">
+        <ChatKitPanel
+          theme={scheme}
+          onWidgetAction={handleWidgetAction}
+          onResponseEnd={handleResponseEnd}
+          onThemeRequest={setScheme}
+        />
+      </div>
+    </main>
+  );
+}

app/api/create-session/route.ts

@@ -0,0 +1,254 @@
+import { WORKFLOW_ID } from "@/lib/config";
+
+export const runtime = "edge";
+
+interface CreateSessionRequestBody {
+  workflow?: { id?: string | null } | null;
+  scope?: { user_id?: string | null } | null;
+  workflowId?: string | null;
+}
+
+const DEFAULT_CHATKIT_BASE = "https://api.openai.com";
+const SESSION_COOKIE_NAME = "chatkit_session_id";
+const SESSION_COOKIE_MAX_AGE = 60 * 60 * 24 * 30; // 30 days
+
+export async function POST(request: Request): Promise<Response> {
+  if (request.method !== "POST") {
+    return methodNotAllowedResponse();
+  }
+  let sessionCookie: string | null = null;
+  try {
+    const openaiApiKey = process.env.OPENAI_API_KEY;
+    if (!openaiApiKey) {
+      return new Response(
+        JSON.stringify({ error: "Missing OPENAI_API_KEY environment variable" }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    const parsedBody = await safeParseJson<CreateSessionRequestBody>(request);
+    const { userId, sessionCookie: resolvedSessionCookie } = await resolveUserId(request);
+    sessionCookie = resolvedSessionCookie;
+    const resolvedWorkflowId =
+      parsedBody?.workflow?.id ?? parsedBody?.workflowId ?? WORKFLOW_ID;
+
+    if (process.env.NODE_ENV !== "production") {
+      console.info("[create-session] handling request", {
+        resolvedWorkflowId,
+        body: JSON.stringify(parsedBody),
+      });
+    }
+
+    if (!resolvedWorkflowId) {
+      return buildJsonResponse(
+        { error: "Missing workflow id" },
+        400,
+        { "Content-Type": "application/json" },
+        sessionCookie
+      );
+    }
+
+    const apiBase = process.env.CHATKIT_API_BASE ?? DEFAULT_CHATKIT_BASE;
+    const url = `${apiBase}/v1/chatkit/sessions`;
+    const upstreamResponse = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${openaiApiKey}`,
+        "OpenAI-Beta": "chatkit_beta=v1",
+      },
+      body: JSON.stringify({
+        workflow: { id: resolvedWorkflowId },
+        user: userId,
+      }),
+    });
+
+    if (process.env.NODE_ENV !== "production") {
+      console.info("[create-session] upstream response", {
+        status: upstreamResponse.status,
+        statusText: upstreamResponse.statusText,
+      });
+    }
+
+    const upstreamJson = (await upstreamResponse.json().catch(() => ({}))) as
+      | Record<string, unknown>
+      | undefined;
+
+    if (!upstreamResponse.ok) {
+      const upstreamError = extractUpstreamError(upstreamJson);
+      console.error("OpenAI ChatKit session creation failed", {
+        status: upstreamResponse.status,
+        statusText: upstreamResponse.statusText,
+        body: upstreamJson,
+      });
+      return buildJsonResponse(
+        {
+          error: upstreamError ?? `Failed to create session: ${upstreamResponse.statusText}`,
+          details: upstreamJson,
+        },
+        upstreamResponse.status,
+        { "Content-Type": "application/json" },
+        sessionCookie
+      );
+    }
+
+    const clientSecret = upstreamJson?.client_secret ?? null;
+    const expiresAfter = upstreamJson?.expires_after ?? null;
+    const responsePayload = {
+      client_secret: clientSecret,
+      expires_after: expiresAfter,
+    };
+
+    return buildJsonResponse(
+      responsePayload,
+      200,
+      { "Content-Type": "application/json" },
+      sessionCookie
+    );
+  } catch (error) {
+    console.error("Create session error", error);
+    return buildJsonResponse(
+      { error: "Unexpected error" },
+      500,
+      { "Content-Type": "application/json" },
+      sessionCookie
+    );
+  }
+}
+
+export async function GET(): Promise<Response> {
+  return methodNotAllowedResponse();
+}
+
+function methodNotAllowedResponse(): Response {
+  return new Response(JSON.stringify({ error: "Method Not Allowed" }), {
+    status: 405,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+async function resolveUserId(request: Request): Promise<{
+  userId: string;
+  sessionCookie: string | null;
+}> {
+  const existing = getCookieValue(request.headers.get("cookie"), SESSION_COOKIE_NAME);
+  if (existing) {
+    return { userId: existing, sessionCookie: null };
+  }
+
+  const generated = typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : Math.random().toString(36).slice(2);
+
+  return {
+    userId: generated,
+    sessionCookie: serializeSessionCookie(generated),
+  };
+}
+
+function getCookieValue(cookieHeader: string | null, name: string): string | null {
+  if (!cookieHeader) {
+    return null;
+  }
+
+  const cookies = cookieHeader.split(";");
+  for (const cookie of cookies) {
+    const [rawName, ...rest] = cookie.split("=");
+    if (!rawName || rest.length === 0) { continue; }
+    if (rawName.trim() === name) { return rest.join("=").trim(); }
+  }
+  return null;
+}
+
+function serializeSessionCookie(value: string): string {
+  const attributes = [
+    `${SESSION_COOKIE_NAME}=${encodeURIComponent(value)}`,
+    "Path=/",
+    `Max-Age=${SESSION_COOKIE_MAX_AGE}`,
+    "HttpOnly",
+    "SameSite=Lax",
+  ];
+
+  if (process.env.NODE_ENV === "production") {
+    attributes.push("Secure");
+  }
+  return attributes.join("; ");
+}
+
+function buildJsonResponse(
+  payload: unknown,
+  status: number,
+  headers: Record<string, string>,
+  sessionCookie: string | null
+): Response {
+  const responseHeaders = new Headers(headers);
+
+  if (sessionCookie) {
+    responseHeaders.append("Set-Cookie", sessionCookie);
+  }
+
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: responseHeaders,
+  });
+}
+
+async function safeParseJson<T>(req: Request): Promise<T | null> {
+  try {
+    const text = await req.text();
+    if (!text) { return null; }
+    return JSON.parse(text) as T;
+  } catch {
+    return null;
+  }
+}
+
+function extractUpstreamError(
+  payload: Record<string, unknown> | undefined
+): string | null {
+  if (!payload) {
+    return null;
+  }
+
+  const error = payload.error;
+  if (typeof error === "string") {
+    return error;
+  }
+
+  if (
+    error &&
+    typeof error === "object" &&
+    "message" in error &&
+    typeof (error as { message?: unknown }).message === "string"
+  ) {
+    return (error as { message: string }).message;
+  }
+
+  const details = payload.details;
+  if (typeof details === "string") {
+    return details;
+  }
+
+  if (details && typeof details === "object" && "error" in details) {
+    const nestedError = (details as { error?: unknown }).error;
+    if (typeof nestedError === "string") {
+      return nestedError;
+    }
+    if (
+      nestedError &&
+      typeof nestedError === "object" &&
+      "message" in nestedError &&
+      typeof (nestedError as { message?: unknown }).message === "string"
+    ) {
+      return (nestedError as { message: string }).message;
+    }
+  }
+
+  if (typeof payload.message === "string") {
+    return payload.message;
+  }
+  return null;
+}

app/globals.css

@@ -0,0 +1,34 @@
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+  color-scheme: light;
+}
+
+:root[data-color-scheme="dark"] {
+  --background: #0a0a0a;
+  --foreground: #ededed;
+  color-scheme: dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-color-scheme]) {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+    color-scheme: dark;
+  }
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: Arial, Helvetica, sans-serif;
+  --font-mono: SFMono-Regular, Consolas, "Liberation Mono", monospace;
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-sans);
+}

app/layout.tsx

@@ -0,0 +1,26 @@
+import Script from "next/script";
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "AgentKit demo",
+  description: "Demo of ChatKit with hosted workflow",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <head>
+        <Script
+          src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
+          strategy="beforeInteractive"
+        />
+      </head>
+      <body className="antialiased">{children}</body>
+    </html>
+  );
+}

app/page.tsx

@@ -0,0 +1,5 @@
+import App from "./App";
+
+export default function Home() {
+  return <App />;
+}

components/ChatKitPanel.tsx

@@ -0,0 +1,418 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { ChatKit, useChatKit } from "@openai/chatkit-react";
+import {
+  STARTER_PROMPTS,
+  PLACEHOLDER_INPUT,
+  GREETING,
+  CREATE_SESSION_ENDPOINT,
+  WORKFLOW_ID,
+} from "@/lib/config";
+import { ErrorOverlay } from "./ErrorOverlay";
+import type { ColorScheme } from "@/hooks/useColorScheme";
+
+export type FactAction = {
+  type: "save";
+  factId: string;
+  factText: string;
+};
+
+type ChatKitPanelProps = {
+  theme: ColorScheme;
+  onWidgetAction: (action: FactAction) => Promise<void>;
+  onResponseEnd: () => void;
+  onThemeRequest: (scheme: ColorScheme) => void;
+};
+
+type ErrorState = {
+  script: string | null;
+  session: string | null;
+  integration: string | null;
+  retryable: boolean;
+};
+
+const isBrowser = typeof window !== "undefined";
+const isDev = process.env.NODE_ENV !== "production";
+
+const createInitialErrors = (): ErrorState => ({
+  script: null,
+  session: null,
+  integration: null,
+  retryable: false,
+});
+
+export function ChatKitPanel({
+  theme,
+  onWidgetAction,
+  onResponseEnd,
+  onThemeRequest,
+}: ChatKitPanelProps) {
+  const processedFacts = useRef(new Set<string>());
+  const [errors, setErrors] = useState<ErrorState>(() => createInitialErrors());
+  const [isInitializingSession, setIsInitializingSession] = useState(true);
+  const isMountedRef = useRef(true);
+  const [scriptStatus, setScriptStatus] = useState<
+    "pending" | "ready" | "error"
+  >(() =>
+    isBrowser && window.customElements?.get("openai-chatkit")
+      ? "ready"
+      : "pending"
+  );
+  const [widgetInstanceKey, setWidgetInstanceKey] = useState(0);
+
+  const setErrorState = useCallback((updates: Partial<ErrorState>) => {
+    setErrors((current) => ({ ...current, ...updates }));
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!isBrowser) {
+      return;
+    }
+
+    let timeoutId: number | undefined;
+
+    const handleLoaded = () => {
+      if (!isMountedRef.current) {
+        return;
+      }
+      setScriptStatus("ready");
+      setErrorState({ script: null });
+    };
+
+    const handleError = (event: Event) => {
+      console.error("Failed to load chatkit.js for some reason", event);
+      if (!isMountedRef.current) {
+        return;
+      }
+      setScriptStatus("error");
+      const detail = (event as CustomEvent<unknown>)?.detail ?? "unknown error";
+      setErrorState({ script: `Error: ${detail}`, retryable: false });
+      setIsInitializingSession(false);
+    };
+
+    window.addEventListener("chatkit-script-loaded", handleLoaded);
+    window.addEventListener(
+      "chatkit-script-error",
+      handleError as EventListener
+    );
+
+    if (window.customElements?.get("openai-chatkit")) {
+      handleLoaded();
+    } else if (scriptStatus === "pending") {
+      timeoutId = window.setTimeout(() => {
+        if (!window.customElements?.get("openai-chatkit")) {
+          handleError(
+            new CustomEvent("chatkit-script-error", {
+              detail:
+                "ChatKit web component is unavailable. Verify that the script URL is reachable.",
+            })
+          );
+        }
+      }, 5000);
+    }
+
+    return () => {
+      window.removeEventListener("chatkit-script-loaded", handleLoaded);
+      window.removeEventListener(
+        "chatkit-script-error",
+        handleError as EventListener
+      );
+      if (timeoutId) {
+        window.clearTimeout(timeoutId);
+      }
+    };
+  }, [scriptStatus, setErrorState]);
+
+  const isWorkflowConfigured = Boolean(
+    WORKFLOW_ID && !WORKFLOW_ID.startsWith("wf_replace")
+  );
+
+  useEffect(() => {
+    if (!isWorkflowConfigured && isMountedRef.current) {
+      setErrorState({
+        session: "Set NEXT_PUBLIC_CHATKIT_WORKFLOW_ID in your .env.local file.",
+        retryable: false,
+      });
+      setIsInitializingSession(false);
+    }
+  }, [isWorkflowConfigured, setErrorState]);
+
+  const handleResetChat = useCallback(() => {
+    processedFacts.current.clear();
+    if (isBrowser) {
+      setScriptStatus(
+        window.customElements?.get("openai-chatkit") ? "ready" : "pending"
+      );
+    }
+    setIsInitializingSession(true);
+    setErrors(createInitialErrors());
+    setWidgetInstanceKey((prev) => prev + 1);
+  }, []);
+
+  const getClientSecret = useCallback(
+    async (currentSecret: string | null) => {
+      if (isDev) {
+        console.info("[ChatKitPanel] getClientSecret invoked", {
+          currentSecretPresent: Boolean(currentSecret),
+          workflowId: WORKFLOW_ID,
+          endpoint: CREATE_SESSION_ENDPOINT,
+        });
+      }
+
+      if (!isWorkflowConfigured) {
+        const detail =
+          "Set NEXT_PUBLIC_CHATKIT_WORKFLOW_ID in your .env.local file.";
+        if (isMountedRef.current) {
+          setErrorState({ session: detail, retryable: false });
+          setIsInitializingSession(false);
+        }
+        throw new Error(detail);
+      }
+
+      if (isMountedRef.current) {
+        if (!currentSecret) {
+          setIsInitializingSession(true);
+        }
+        setErrorState({ session: null, integration: null, retryable: false });
+      }
+
+      try {
+        const response = await fetch(CREATE_SESSION_ENDPOINT, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            workflow: { id: WORKFLOW_ID },
+          }),
+        });
+
+        const raw = await response.text();
+
+        if (isDev) {
+          console.info("[ChatKitPanel] createSession response", {
+            status: response.status,
+            ok: response.ok,
+            bodyPreview: raw.slice(0, 1600),
+          });
+        }
+
+        let data: Record<string, unknown> = {};
+        if (raw) {
+          try {
+            data = JSON.parse(raw) as Record<string, unknown>;
+          } catch (parseError) {
+            console.error(
+              "Failed to parse create-session response",
+              parseError
+            );
+          }
+        }
+
+        if (!response.ok) {
+          const detail = extractErrorDetail(data, response.statusText);
+          console.error("Create session request failed", {
+            status: response.status,
+            body: data,
+          });
+          throw new Error(detail);
+        }
+
+        const clientSecret = data?.client_secret as string | undefined;
+        if (!clientSecret) {
+          throw new Error("Missing client secret in response");
+        }
+
+        if (isMountedRef.current) {
+          setErrorState({ session: null, integration: null });
+        }
+
+        return clientSecret;
+      } catch (error) {
+        console.error("Failed to create ChatKit session", error);
+        const detail =
+          error instanceof Error
+            ? error.message
+            : "Unable to start ChatKit session.";
+        if (isMountedRef.current) {
+          setErrorState({ session: detail, retryable: false });
+        }
+        throw error instanceof Error ? error : new Error(detail);
+      } finally {
+        if (isMountedRef.current && !currentSecret) {
+          setIsInitializingSession(false);
+        }
+      }
+    },
+    [isWorkflowConfigured, setErrorState]
+  );
+
+  const chatkit = useChatKit({
+    api: { getClientSecret },
+    theme: {
+      colorScheme: theme,
+      color: {
+        grayscale: {
+          hue: 220,
+          tint: 6,
+          shade: theme === "dark" ? -1 : -4,
+        },
+        accent: {
+          primary: theme === "dark" ? "#f1f5f9" : "#0f172a",
+          level: 1,
+        },
+      },
+      radius: "round",
+    },
+    startScreen: {
+      greeting: GREETING,
+      prompts: STARTER_PROMPTS,
+    },
+    composer: {
+      placeholder: PLACEHOLDER_INPUT,
+    },
+    threadItemActions: {
+      feedback: false,
+    },
+    onClientTool: async (invocation: {
+      name: string;
+      params: Record<string, unknown>;
+    }) => {
+      if (invocation.name === "switch_theme") {
+        const requested = invocation.params.theme;
+        if (requested === "light" || requested === "dark") {
+          if (isDev) {
+            console.debug("[ChatKitPanel] switch_theme", requested);
+          }
+          onThemeRequest(requested);
+          return { success: true };
+        }
+        return { success: false };
+      }
+
+      if (invocation.name === "record_fact") {
+        const id = String(invocation.params.fact_id ?? "");
+        const text = String(invocation.params.fact_text ?? "");
+        if (!id || processedFacts.current.has(id)) {
+          return { success: true };
+        }
+        processedFacts.current.add(id);
+        void onWidgetAction({
+          type: "save",
+          factId: id,
+          factText: text.replace(/\s+/g, " ").trim(),
+        });
+        return { success: true };
+      }
+
+      return { success: false };
+    },
+    onResponseEnd: () => {
+      onResponseEnd();
+    },
+    onResponseStart: () => {
+      setErrorState({ integration: null, retryable: false });
+    },
+    onThreadChange: () => {
+      processedFacts.current.clear();
+    },
+    onError: ({ error }: { error: unknown }) => {
+      // Note that Chatkit UI handles errors for your users.
+      // Thus, your app code doesn't need to display errors on UI.
+      console.error("ChatKit error", error);
+    },
+  });
+
+  const activeError = errors.session ?? errors.integration;
+  const blockingError = errors.script ?? activeError;
+
+  if (isDev) {
+    console.debug("[ChatKitPanel] render state", {
+      isInitializingSession,
+      hasControl: Boolean(chatkit.control),
+      scriptStatus,
+      hasError: Boolean(blockingError),
+      workflowId: WORKFLOW_ID,
+    });
+  }
+
+  return (
+    <div className="relative flex h-[90vh] w-full flex-col overflow-hidden bg-white shadow-sm transition-colors dark:bg-slate-900">
+      <ChatKit
+        key={widgetInstanceKey}
+        control={chatkit.control}
+        className={
+          blockingError || isInitializingSession
+            ? "pointer-events-none opacity-0"
+            : "block h-full w-full"
+        }
+      />
+      <ErrorOverlay
+        error={blockingError}
+        fallbackMessage={
+          blockingError || !isInitializingSession
+            ? null
+            : "Loading assistant session..."
+        }
+        onRetry={blockingError && errors.retryable ? handleResetChat : null}
+        retryLabel="Restart chat"
+      />
+    </div>
+  );
+}
+
+function extractErrorDetail(
+  payload: Record<string, unknown> | undefined,
+  fallback: string
+): string {
+  if (!payload) {
+    return fallback;
+  }
+
+  const error = payload.error;
+  if (typeof error === "string") {
+    return error;
+  }
+
+  if (
+    error &&
+    typeof error === "object" &&
+    "message" in error &&
+    typeof (error as { message?: unknown }).message === "string"
+  ) {
+    return (error as { message: string }).message;
+  }
+
+  const details = payload.details;
+  if (typeof details === "string") {
+    return details;
+  }
+
+  if (details && typeof details === "object" && "error" in details) {
+    const nestedError = (details as { error?: unknown }).error;
+    if (typeof nestedError === "string") {
+      return nestedError;
+    }
+    if (
+      nestedError &&
+      typeof nestedError === "object" &&
+      "message" in nestedError &&
+      typeof (nestedError as { message?: unknown }).message === "string"
+    ) {
+      return (nestedError as { message: string }).message;
+    }
+  }
+
+  if (typeof payload.message === "string") {
+    return payload.message;
+  }
+
+  return fallback;
+}

components/ErrorOverlay.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+type ErrorOverlayProps = {
+  error: string | null;
+  fallbackMessage?: ReactNode;
+  onRetry?: (() => void) | null;
+  retryLabel?: string;
+};
+
+export function ErrorOverlay({
+  error,
+  fallbackMessage,
+  onRetry,
+  retryLabel,
+}: ErrorOverlayProps) {
+  if (!error && !fallbackMessage) {
+    return null;
+  }
+
+  const content = error ?? fallbackMessage;
+
+  if (!content) {
+    return null;
+  }
+
+  return (
+    <div className="pointer-events-none absolute inset-0 z-10 flex h-full w-full flex-col justify-center rounded-[inherit] bg-white/85 p-6 text-center backdrop-blur dark:bg-slate-900/90">
+      <div className="pointer-events-auto mx-auto w-full max-w-md rounded-xl bg-white px-6 py-4 text-lg font-medium text-slate-700 dark:bg-transparent dark:text-slate-100">
+        <div>{content}</div>
+        {error && onRetry ? (
+          <button
+            type="button"
+            className="mt-4 inline-flex items-center justify-center rounded-lg bg-slate-900 px-4 py-2 text-sm font-semibold text-white shadow-none transition hover:bg-slate-800 focus:outline-none focus-visible:ring-2 focus-visible:ring-slate-500 focus-visible:ring-offset-2 dark:bg-slate-100 dark:text-slate-900 dark:hover:bg-slate-200"
+            onClick={onRetry}
+          >
+            {retryLabel ?? "Restart chat"}
+          </button>
+        ) : null}
+      </div>
+    </div>
+  );
+}

eslint.config.mjs

@@ -0,0 +1,25 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+  {
+    ignores: [
+      "node_modules/**",
+      ".next/**",
+      "out/**",
+      "build/**",
+      "next-env.d.ts",
+    ],
+  },
+];
+
+export default eslintConfig;

hooks/useColorScheme.ts

@@ -0,0 +1,178 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+
+export type ColorScheme = "light" | "dark";
+export type ColorSchemePreference = ColorScheme | "system";
+
+const STORAGE_KEY = "chatkit-color-scheme";
+const PREFERS_DARK_QUERY = "(prefers-color-scheme: dark)";
+
+type MediaQueryCallback = (event: MediaQueryListEvent) => void;
+
+function getMediaQuery(): MediaQueryList | null {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return null;
+  }
+  try {
+    return window.matchMedia(PREFERS_DARK_QUERY);
+  } catch (error) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn("[useColorScheme] matchMedia failed", error);
+    }
+    return null;
+  }
+}
+
+function getSystemSnapshot(): ColorScheme {
+  const media = getMediaQuery();
+  return media?.matches ? "dark" : "light";
+}
+
+function getServerSnapshot(): ColorScheme {
+  return "light";
+}
+
+function subscribeSystem(listener: () => void): () => void {
+  const media = getMediaQuery();
+  if (!media) {
+    return () => { };
+  }
+
+  const handler: MediaQueryCallback = () => listener();
+
+  if (typeof media.addEventListener === "function") {
+    media.addEventListener("change", handler);
+    return () => media.removeEventListener("change", handler);
+  }
+
+  // Fallback for older browsers or environments.
+  if (typeof media.addListener === "function") {
+    media.addListener(handler);
+    return () => media.removeListener(handler);
+  }
+
+  return () => { };
+}
+
+function readStoredPreference(): ColorSchemePreference | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (raw === "light" || raw === "dark") {
+      return raw;
+    }
+    return raw === "system" ? "system" : null;
+  } catch (error) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn("[useColorScheme] Failed to read preference", error);
+    }
+    return null;
+  }
+}
+
+function persistPreference(preference: ColorSchemePreference): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+  try {
+    if (preference === "system") {
+      window.localStorage.removeItem(STORAGE_KEY);
+    } else {
+      window.localStorage.setItem(STORAGE_KEY, preference);
+    }
+  } catch (error) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn("[useColorScheme] Failed to persist preference", error);
+    }
+  }
+}
+
+function applyDocumentScheme(scheme: ColorScheme): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+  const root = document.documentElement;
+  root.dataset.colorScheme = scheme;
+  root.classList.toggle("dark", scheme === "dark");
+  root.style.colorScheme = scheme;
+}
+
+type UseColorSchemeResult = {
+  scheme: ColorScheme;
+  preference: ColorSchemePreference;
+  setScheme: (scheme: ColorScheme) => void;
+  setPreference: (preference: ColorSchemePreference) => void;
+  resetPreference: () => void;
+};
+
+function useSystemColorScheme(): ColorScheme {
+  return useSyncExternalStore(subscribeSystem, getSystemSnapshot, getServerSnapshot);
+}
+
+export function useColorScheme(
+  initialPreference: ColorSchemePreference = "system"
+): UseColorSchemeResult {
+  const systemScheme = useSystemColorScheme();
+
+  const [preference, setPreferenceState] = useState<ColorSchemePreference>(() => {
+    if (typeof window === "undefined") {
+      return initialPreference;
+    }
+    return readStoredPreference() ?? initialPreference;
+  });
+
+  const scheme = useMemo<ColorScheme>(
+    () => (preference === "system" ? systemScheme : preference),
+    [preference, systemScheme]
+  );
+
+  useEffect(() => {
+    persistPreference(preference);
+  }, [preference]);
+
+  useEffect(() => {
+    applyDocumentScheme(scheme);
+  }, [scheme]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const handleStorage = (event: StorageEvent) => {
+      if (event.key !== STORAGE_KEY) {
+        return;
+      }
+      setPreferenceState((current) => {
+        const stored = readStoredPreference();
+        return stored ?? current;
+      });
+    };
+
+    window.addEventListener("storage", handleStorage);
+    return () => window.removeEventListener("storage", handleStorage);
+  }, []);
+
+  const setPreference = useCallback((next: ColorSchemePreference) => {
+    setPreferenceState(next);
+  }, []);
+
+  const setScheme = useCallback((next: ColorScheme) => {
+    setPreferenceState(next);
+  }, []);
+
+  const resetPreference = useCallback(() => {
+    setPreferenceState("system");
+  }, []);
+
+  return {
+    scheme,
+    preference,
+    setScheme,
+    setPreference,
+    resetPreference,
+  };
+}

lib/config.ts

@@ -0,0 +1,17 @@
+import { StartScreenPrompt } from "@openai/chatkit";
+
+export const WORKFLOW_ID = process.env.NEXT_PUBLIC_CHATKIT_WORKFLOW_ID?.trim() ?? "";
+
+export const CREATE_SESSION_ENDPOINT = "/api/create-session";
+
+export const STARTER_PROMPTS: StartScreenPrompt[] = [
+  {
+    label: "What can you do?",
+    prompt: "What can you do?",
+    icon: "circle-question",
+  },
+];
+
+export const PLACEHOLDER_INPUT = "Ask anything...";
+
+export const GREETING = "How can I help you today?";

next.config.ts

@@ -0,0 +1,12 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  webpack: (config) => {
+    config.resolve.alias = {
+      ...(config.resolve.alias ?? {}),
+    };
+    return config;
+  },
+};
+
+export default nextConfig;

package.json

@@ -0,0 +1,28 @@
+{
+  "name": "openai-chatkit-starter-app",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@openai/chatkit-react": "^0",
+    "next": "^15.5.4",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "15.5.4",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

postcss.config.mjs

@@ -0,0 +1,5 @@
+const config = {
+  plugins: ["@tailwindcss/postcss"],
+};
+
+export default config;

tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}