# Chatkit Frontend > Skill: ChatKit Frontend Setup - Skill: `fatima367/chatkit-frontend` (Agent Skill) - Install (CLI): `npx skillmds@latest add fatima367/chatkit-frontend` - Raw SKILL.md: https://api.skillmd.com/api/skills/fatima367/chatkit-frontend/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: Fatima367 (https://skillmd.com/u/fatima367) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/fatima367/chatkit-frontend --- # Skill: ChatKit Frontend Setup ## Metadata - **Name**: chatkit-frontend - **Category**: setup - **Tags**: chatkit, frontend, react, typescript ## Description Creates a ChatKit React frontend with TypeScript, dark theme, and conversation persistence. Template uses Vite but works with any React framework (Next.js, CRA, Docusaurus, etc.). ## Inputs | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | theme | string | No | dark | Color scheme: dark, light | | greeting | string | No | Welcome! | Start screen greeting | | backendUrl | string | No | http://localhost:8000/chatkit | Backend API URL | | port | number | No | 3000 | Dev server port | | layout | string | No | fullpage | Layout: fullpage, popup-right, popup-left | ## Outputs - `frontend/index.html` - HTML with CDN script - `frontend/package.json` - Dependencies - `frontend/tsconfig.json` - TypeScript config - `frontend/vite.config.ts` - Vite config - `frontend/src/main.tsx` - Entry point - `frontend/src/App.tsx` - ChatKit component ## Prerequisites - Node.js 18+ - npm or yarn ## Execution Steps ### 1. Create Directory Structure ``` frontend/ ├── index.html ├── package.json ├── tsconfig.json ├── vite.config.ts └── src/ ├── main.tsx └── App.tsx ``` ### 2. Generate package.json ```json { "name": "chatkit-frontend", "private": true, "version": "1.0.0", "type": "module", "scripts": { "dev": "vite", "build": "tsc && vite build", "preview": "vite preview" }, "dependencies": { "@openai/chatkit-react": "^1.3.0", "react": "^18.3.1", "react-dom": "^18.3.1" }, "devDependencies": { "@types/react": "^18.3.12", "@types/react-dom": "^18.3.1", "@vitejs/plugin-react": "^4.3.4", "typescript": "^5.6.3", "vite": "^6.0.3" } } ``` ### 3. Generate index.html **CRITICAL: CDN script required** ```html ChatKit App

``` ### 4. Generate App.tsx **CRITICAL Configuration:** - `domainKey: 'localhost'` - REQUIRED for local dev - Use `label` in prompts, NOT `name` - Do NOT use `icon` property ```tsx import { ChatKit, useChatKit } from '@openai/chatkit-react' import { useState, useEffect } from 'react' function App() { const [initialThread, setInitialThread] = useState(null) const [isReady, setIsReady] = useState(false) useEffect(() => { const savedThread = localStorage.getItem('chatkit-thread-id') setInitialThread(savedThread) setIsReady(true) }, []) const { control } = useChatKit({ api: { url: '{{BACKEND_URL}}', domainKey: 'localhost', }, initialThread: initialThread, theme: { colorScheme: '{{THEME}}', color: { grayscale: { hue: 220, tint: 6, shade: -1 }, accent: { primary: '#4cc9f0', level: 1 }, }, radius: 'round', }, startScreen: { greeting: '{{GREETING}}', prompts: [ { label: 'Hello', prompt: 'Say hello and introduce yourself' }, { label: 'Help', prompt: 'What can you help me with?' }, ], }, composer: { placeholder: 'Type a message...', }, onThreadChange: ({ threadId }) => { if (threadId) { localStorage.setItem('chatkit-thread-id', threadId) } }, onError: ({ error }) => console.error('ChatKit error:', error), }) if (!isReady) return

return (

ChatKit App

) } export default App ``` ### 5. Generate vite.config.ts ```ts import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], server: { port: {{PORT}}, } }) ``` ### 6. Generate tsconfig.json ```json { "compilerOptions": { "target": "ES2020", "useDefineForClassFields": true, "lib": ["ES2020", "DOM", "DOM.Iterable"], "module": "ESNext", "skipLibCheck": true, "moduleResolution": "bundler", "allowImportingTsExtensions": true, "resolveJsonModule": true, "isolatedModules": true, "noEmit": true, "jsx": "react-jsx", "strict": true }, "include": ["src"] } ``` ### 7. Generate src/main.tsx ```tsx import React from 'react' import ReactDOM from 'react-dom/client' import App from './App' ReactDOM.createRoot(document.getElementById('root')!).render( , ) ``` ## Validation - [ ] `npm install` completes without errors - [ ] `npm run dev` starts dev server - [ ] Chat UI renders (not blank) - [ ] Messages can be sent - [ ] Thread persists on page refresh ## Common Errors | Error | Fix | |-------|-----| | Blank screen | Add CDN script to index.html | | `FatalAppError: Invalid input at api` | Add `domainKey: 'localhost'` | | `Unrecognized key "name"` | Use `label` not `name` | | `Unrecognized key "icon"` | Remove `icon` property | ## Layout Variants ### Popup Chat (Bottom-Right) - Recommended For a floating popup chat that appears in the bottom-right corner: ```tsx import { ChatKit, useChatKit } from '@openai/chatkit-react' import { useState, useEffect } from 'react' function App() { const [initialThread, setInitialThread] = useState(null) const [isReady, setIsReady] = useState(false) const [isChatOpen, setIsChatOpen] = useState(false) useEffect(() => { const savedThread = localStorage.getItem('chatkit-thread-id') setInitialThread(savedThread) setIsReady(true) }, []) const { control } = useChatKit({ api: { url: '{{BACKEND_URL}}', domainKey: 'localhost', }, initialThread: initialThread, theme: { colorScheme: 'dark', color: { grayscale: { hue: 220, tint: 6, shade: -1 }, accent: { primary: '#4cc9f0', level: 1 }, }, radius: 'round', }, startScreen: { greeting: '{{GREETING}}', prompts: [ { label: 'Hello', prompt: 'Say hello' }, { label: 'Help', prompt: 'What can you help me with?' }, ], }, onThreadChange: ({ threadId }) => { if (threadId) localStorage.setItem('chatkit-thread-id', threadId) }, }) if (!isReady) return

return (

{/* Your main page content here */}

Your App

{/* Floating Chat Button (bottom-right) */} {!isChatOpen && ( )} {/* Chat Popup (bottom-right) */} {isChatOpen && ( <> {/* Backdrop */}

setIsChatOpen(false)} style={{ position: 'fixed', inset: 0, background: 'rgba(0, 0, 0, 0.3)', zIndex: 999 }} /> {/* Popup Window */}

{/* Header */}

Assistant

{/* Chat Content */}

)} {/* CSS Animation */}

) } export default App ``` ### Key Popup Layout Features: - **Floating button**: Fixed position bottom-right, 60x60px circular - **Popup window**: 420x600px, positioned above the button - **Backdrop**: Click to close, semi-transparent overlay - **Header**: Title, "New Chat" button, close button - **Animation**: Smooth scale + fade entrance ### Positioning Variants: - **Bottom-right**: `right: '2rem'` (recommended) - **Bottom-left**: `left: '2rem'` - Change both the floating button AND popup window positions ## Related Skills - `chatkit-backend` - Python backend - `chatkit-store` - Store implementation