0
# Development Console
1

2
Development tools for debugging and monitoring CopilotKit applications. The dev console provides version checking, update notifications, and debug utilities.
3

4
## Capabilities
5

6
### CopilotDevConsole
7

8
Development console component that displays version information, update notifications, and debug menu. Automatically shown in development mode unless disabled.
9

10
```typescript { .api }
11
/**
12
 * Development console for debugging CopilotKit applications
13
 * Automatically displays in development mode based on CopilotKit context configuration
14
 * @returns Rendered dev console or null if hidden/disabled
15
 */
16
function CopilotDevConsole(): JSX.Element | null;
17
```
18

19
**Features:**
20

21
- **Version Checking**: Automatically checks for new CopilotKit versions
22
- **Update Notifications**: Displays alerts when updates are available with severity levels (low, medium, high)
23
- **Debug Menu**: Provides options to:
24
  - Log readable context to console
25
  - Log registered actions to console
26
  - Log messages to console
27
  - Copy installation command for updates
28
  - Hide the dev console
29
- **Advisory Messages**: Shows important notices about breaking changes or security updates
30

31
**Controlling Display:**
32

33
The dev console is controlled via the `showDevConsole` prop in the CopilotKit provider:
34

35
```typescript
36
import { CopilotKit } from "@copilotkit/react-core";
37
import { CopilotDevConsole } from "@copilotkit/react-ui";
38

39
function App() {
40
  return (
41
    <CopilotKit
42
      runtimeUrl="/api/copilotkit"
43
      showDevConsole={true} // Enable in production (default: true in dev, false in prod)
44
    >
45
      <YourApp />
46
      <CopilotDevConsole />
47
    </CopilotKit>
48
  );
49
}
50
```
51

52
**Default Behavior:**
53

54
- **Development**: Automatically shown when `process.env.NODE_ENV === 'development'`
55
- **Production**: Hidden by default, can be enabled with `showDevConsole={true}`
56

57
**Usage Example - Always Show:**
58

59
```typescript
60
import { CopilotKit } from "@copilotkit/react-core";
61
import { CopilotDevConsole } from "@copilotkit/react-ui";
62

63
function App() {
64
  return (
65
    <CopilotKit
66
      runtimeUrl="/api/copilotkit"
67
      showDevConsole={true}
68
    >
69
      <YourApp />
70
      <CopilotDevConsole />
71
    </CopilotKit>
72
  );
73
}
74
```
75

76
**Usage Example - Always Hide:**
77

78
```typescript
79
import { CopilotKit } from "@copilotkit/react-core";
80

81
function App() {
82
  return (
83
    <CopilotKit
84
      runtimeUrl="/api/copilotkit"
85
      showDevConsole={false}
86
    >
87
      <YourApp />
88
      {/* CopilotDevConsole not included */}
89
    </CopilotKit>
90
  );
91
}
92
```
93

94
**Usage Example - Conditional Display:**
95

96
```typescript
97
import { CopilotKit } from "@copilotkit/react-core";
98
import { CopilotDevConsole } from "@copilotkit/react-ui";
99

100
function App() {
101
  const isDev = process.env.NODE_ENV === "development";
102
  const isStaging = process.env.NEXT_PUBLIC_ENV === "staging";
103

104
  return (
105
    <CopilotKit
106
      runtimeUrl="/api/copilotkit"
107
      showDevConsole={isDev || isStaging}
108
    >
109
      <YourApp />
110
      <CopilotDevConsole />
111
    </CopilotKit>
112
  );
113
}
114
```
115

116
### shouldShowDevConsole
117

118
Utility function to determine whether the dev console should be displayed. Checks the `showDevConsole` configuration and environment.
119

120
```typescript { .api }
121
/**
122
 * Determines if dev console should be shown based on configuration
123
 * Re-exported from @copilotkit/react-core for convenience
124
 * @param showDevConsole - Configuration value from CopilotKit provider (optional)
125
 * @returns Whether dev console should be displayed
126
 */
127
function shouldShowDevConsole(showDevConsole?: boolean): boolean;
128
```
129

130
**Usage Example:**
131

132
```typescript
133
import { shouldShowDevConsole } from "@copilotkit/react-ui";
134

135
function CustomDevTools({ enabled }: { enabled: boolean }) {
136
  if (!shouldShowDevConsole(enabled)) {
137
    return null;
138
  }
139

140
  return (
141
    <div className="dev-tools">
142
      <h3>Development Tools</h3>
143
      {/* Custom dev tools UI */}
144
    </div>
145
  );
146
}
147
```
148

149
### Version Information
150

151
Type for representing version information displayed in the dev console.
152

153
**Note:** This type is internal and not directly exported. It's provided here for reference when working with version checking features.
154

155
```typescript { .api }
156
interface CopilotKitVersion {
157
  /** Current installed version */
158
  current: string;
159

160
  /** Latest available version from npm/CDN */
161
  latest: string;
162

163
  /** Update urgency level */
164
  severity: "low" | "medium" | "high";
165

166
  /** Optional advisory message about the update */
167
  advisory: string | null;
168

169
  /** Timestamp of last version check */
170
  lastChecked: number;
171
}
172
```
173

174
**Severity Levels:**
175

176
- **low**: Minor updates, non-breaking changes, optional upgrade
177
- **medium**: Recommended updates with new features or improvements
178
- **high**: Critical updates, security fixes, or breaking changes requiring attention
179

180
**Usage in Console:**
181

182
The dev console automatically fetches and displays version information:
183

184
```typescript
185
// Example version data structure
186
const versionInfo: CopilotKitVersion = {
187
  current: "1.10.6",
188
  latest: "1.12.0",
189
  severity: "medium",
190
  advisory: "This update includes new chat customization options and performance improvements.",
191
  lastChecked: Date.now(),
192
};
193
```
194

195
### Debug Menu Options
196

197
The dev console provides several debug utilities accessible through the menu:
198

199
**Log Readables:**
200
Logs all readable context (shared state) registered with CopilotKit to the browser console. Useful for debugging context availability.
201

202
```typescript
203
// Console output example
204
{
205
  readables: [
206
    { key: "user", value: { name: "Alice", role: "admin" } },
207
    { key: "document", value: { id: "doc-123", title: "My Document" } }
208
  ]
209
}
210
```
211

212
**Log Actions:**
213
Logs all registered CopilotKit actions to the browser console. Shows available actions, their parameters, and descriptions.
214

215
```typescript
216
// Console output example
217
{
218
  actions: [
219
    {
220
      name: "saveDocument",
221
      description: "Save the current document",
222
      parameters: { title: "string", content: "string" }
223
    },
224
    {
225
      name: "searchUsers",
226
      description: "Search for users by name",
227
      parameters: { query: "string" }
228
    }
229
  ]
230
}
231
```
232

233
**Log Messages:**
234
Logs all chat messages to the browser console. Shows full message history with metadata.
235

236
```typescript
237
// Console output example
238
{
239
  messages: [
240
    { id: "msg-1", role: "user", content: "Hello", timestamp: 1234567890 },
241
    { id: "msg-2", role: "assistant", content: "Hi there!", timestamp: 1234567891 }
242
  ]
243
}
244
```
245

246
**Copy Install Command:**
247
Copies the appropriate package manager command to install the latest version to clipboard:
248

249
```bash
250
npm install @copilotkit/react-core@latest @copilotkit/react-ui@latest
251
# or
252
pnpm add @copilotkit/react-core@latest @copilotkit/react-ui@latest
253
# or
254
yarn add @copilotkit/react-core@latest @copilotkit/react-ui@latest
255
```
256

257
**Hide Console:**
258
Hides the dev console for the current session. Can be shown again by refreshing the page (if still in dev mode) or programmatically.
259

260
### Styling the Dev Console
261

262
The dev console can be styled using CSS custom properties:
263

264
```typescript { .api }
265
interface CopilotKitCSSProperties {
266
  /** Dev console background color */
267
  "--copilot-kit-dev-console-bg"?: string;
268

269
  /** Dev console text color */
270
  "--copilot-kit-dev-console-text"?: string;
271
}
272
```
273

274
**Usage Example:**
275

276
```typescript
277
import { CopilotKit } from "@copilotkit/react-core";
278
import { CopilotDevConsole, CopilotKitCSSProperties } from "@copilotkit/react-ui";
279

280
function App() {
281
  const styles: CopilotKitCSSProperties = {
282
    "--copilot-kit-dev-console-bg": "#1a1a1a",
283
    "--copilot-kit-dev-console-text": "#00ff00",
284
  };
285

286
  return (
287
    <div style={styles}>
288
      <CopilotKit runtimeUrl="/api/copilotkit" showDevConsole={true}>
289
        <YourApp />
290
        <CopilotDevConsole />
291
      </CopilotKit>
292
    </div>
293
  );
294
}
295
```
296

297
Or with CSS:
298

299
```css
300
.app-container {
301
  --copilot-kit-dev-console-bg: #1a1a1a;
302
  --copilot-kit-dev-console-text: #00ff00;
303
}
304

305
/* Alternative theme */
306
.light-theme {
307
  --copilot-kit-dev-console-bg: #ffffff;
308
  --copilot-kit-dev-console-text: #333333;
309
}
310
```
311

312
### Best Practices
313

314
**Development:**
315
- Keep dev console enabled during development for easy debugging
316
- Use the debug menu to inspect readables, actions, and messages
317
- Monitor update notifications to stay current with CopilotKit releases
318

319
**Production:**
320
- Disable dev console in production builds for cleaner UI
321
- Consider enabling for specific testing/staging environments
322
- Use environment variables to control visibility
323

324
**Debugging Workflow:**
325

326
```typescript
327
import { CopilotKit } from "@copilotkit/react-core";
328
import { CopilotDevConsole } from "@copilotkit/react-ui";
329

330
function App() {
331
  // Enable in dev and staging
332
  const showConsole =
333
    process.env.NODE_ENV === "development" ||
334
    process.env.NEXT_PUBLIC_ENV === "staging";
335

336
  return (
337
    <CopilotKit
338
      runtimeUrl="/api/copilotkit"
339
      showDevConsole={showConsole}
340
    >
341
      <YourApp />
342
      {/* Dev console helps debug integration issues */}
343
      <CopilotDevConsole />
344
    </CopilotKit>
345
  );
346
}
347
```
348

349
### Version Check Behavior
350

351
The dev console automatically checks for updates:
352

353
- **First Load**: Checks immediately on mount
354
- **Caching**: Caches version info in localStorage to avoid excessive API calls
355
- **Cache Duration**: 1 hour - will only re-check after the cache expires
356
- **Update Check**: Re-checks when cache expires or on first load after clearing localStorage
357
- **Display**: Shows notification badge when updates are available
358

359
**Version Check Source:**
360

361
The console fetches version information from the CopilotKit API (`https://api.cloud.copilotkit.ai/check-for-updates`) to compare with the installed version. This helps developers stay aware of important updates without manual checking. The check is non-blocking and failures are silently ignored to prevent disrupting development.
362

363
### Troubleshooting
364

365
**Dev Console Not Showing:**
366

367
1. Check `showDevConsole` prop in CopilotKit provider
368
2. Verify `CopilotDevConsole` component is rendered
369
3. Check if console was manually hidden via debug menu
370
4. Verify NODE_ENV is set correctly
371

372
**Version Check Failed:**
373

374
1. Check network connectivity
375
2. Verify CDN accessibility
376
3. Check browser console for fetch errors
377
4. May be blocked by ad blockers or privacy extensions
378

379
**Debug Menu Not Working:**
380

381
1. Ensure CopilotKit context is properly initialized
382
2. Check that actions/readables are registered
383
3. Verify console access permissions in browser
384