@ainativekit/devtools

Development tools for building and testing ChatGPT Apps using ChatGPT Apps SDK

A powerful, zero-configuration development environment for building ChatGPT apps. Simulate the ChatGPT production environment locally with interactive controls for testing different states, themes, and device types.

✨ Features

• 🎭 Mock ChatGPT Environment - Simulates window.openai API exactly like production
• 🎨 Theme Switching - Test light and dark themes instantly
• 📱 Device Simulation - Desktop (768px), Tablet (576px), Mobile (380px) viewports aligned with OpenAI Apps SDK
• 🔄 State Testing - Loading, data, and error states with customizable delays
• 🐛 Debug Overlays - Visual boundary indicators for development
• 🚀 Zero Configuration - Works out of the box with sensible defaults
• 📦 Production Ready - Clean separation between dev tools and widget code
• 🔌 ChatGPT Apps SDK Compatible - Works with any ChatGPT Apps SDK implementation

📋 Requirements

• React 18.0.0 or higher
• Node.js 18.0.0 or higher
• Modern browser with ES2020+ support
  • Chrome 80+, Firefox 75+, Safari 13.1+, Edge 80+

Optional Dependencies

• @ainativekit/ui 1.0.0 or higher (optional, but recommended for enhanced theming)
  • DevTools includes basic theme support out of the box
  • For full design system integration, install @ainativekit/ui and use AppsSDKUIProvider
  • See usage examples below for both standalone and integrated approaches

📦 Installation

npm install --save-dev @ainativekit/devtools

or with yarn:

yarn add -D @ainativekit/devtools

🚀 Quick Start

Standalone Usage (No Dependencies)

DevTools works out of the box with built-in theme support:

import { DevContainer } from '@ainativekit/devtools';
import App from './App';

// Only use DevContainer in development
const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
  import.meta.env.DEV ? (
    <DevContainer>
      <App />
    </DevContainer>
  ) : (
    <App />
  )
);

Enhanced Usage (with @ainativekit/ui)

For full design system integration and advanced theming:

import { DevContainer } from '@ainativekit/devtools';
import { ThemeProvider } from '@ainativekit/ui';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
  <ThemeProvider>
    {import.meta.env.DEV ? (
      <DevContainer>
        <App />
      </DevContainer>
    ) : (
      <App />
    )}
  </ThemeProvider>
);

With Custom Data Loader

<DevContainer
  dataLoader={async () => {
    // Return your widget-specific mock data
    const response = await fetch('/api/mock-data');
    return response.json();
  }}
  loadingDelay={3000} // Test loading states
  theme="dark" // Start with dark theme
>
  <YourWidget />
</DevContainer>

Multiple Widgets with Widget-Specific Data Loaders (v1.0.0+)

DevContainer automatically detects when you have multiple widgets and shows a selector. Each widget can have its own data loader:

import { DevContainer } from '@ainativekit/devtools';
import { AppsSDKUIProvider } from '@ainativekit/ui';
import CarouselWidget from './widgets/CarouselWidget';
import MapWidget from './widgets/MapWidget';
import ListWidget from './widgets/ListWidget';
import AlbumWidget from './widgets/AlbumWidget';

function App() {
  return (
    <AppsSDKUIProvider linkComponent="a">
      <DevContainer
        widgets={[
          {
            id: 'carousel',
            name: 'Pizza Carousel',
            component: CarouselWidget,
            dataLoader: () => carouselData,
            emptyDataLoader: () => emptyCarouselData
          },
          {
            id: 'map',
            name: 'Pizza Map',
            component: MapWidget,
            dataLoader: () => mapData
          },
          {
            id: 'list',
            name: 'Pizza List',
            component: ListWidget,
            dataLoader: () => listData,
            emptyDataLoader: () => emptyListData
          },
          {
            id: 'album',
            name: 'Photo Albums',
            component: AlbumWidget,
            dataLoader: () => albumData
          }
        ]}
        loadingDelay={1500}
        theme="light"
        autoLoad={true}
        defaultWidget="carousel"
      />
    </AppsSDKUIProvider>
  );
}

Features:

• Single dev server for all widgets
• Widget-specific data loaders (v1.0.0+)
• Automatic widget selector (only shows when multiple widgets)
• URL support (?widget=map) for deep linking
• Persistent widget selection
• Auto-reload data when switching widgets

📖 API Reference

DevContainer Props

Single Widget Mode

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | React.ReactNode | - | Single widget component | | dataLoader | () => Promise<any> \| any | - | Data loader function | | emptyDataLoader | () => Promise<any> \| any | - | Empty state data loader |

Multi-Widget Mode

| Prop | Type | Default | Description | |------|------|---------|-------------| | widgets | Widget[] | - | Array of widget configurations | | dataLoaders | Record<string, Function> | {} | Map of global data loader functions | | emptyDataLoaders | Record<string, Function> | {} | Map of global empty data loader functions | | defaultDataLoader | string | - | Key for default data loader | | defaultWidget | string | - | ID of default widget to show |

Widget Type (v1.0.0+)

| Property | Type | Required | Description | |----------|------|----------|-------------| | id | string | Yes | Unique identifier for the widget | | name | string | Yes | Display name for the widget selector | | component | React.ComponentType | Yes | The widget component | | dataLoader | () => Promise<any> \| any | No | Widget-specific data loader (single, hides dropdown) | | emptyDataLoader | () => Promise<any> \| any | No | Widget-specific empty state data loader | | dataLoaders | Record<string, Function> | No | Multiple named data loaders (v1.2.0+, shows dropdown) | | emptyDataLoaders | Record<string, Function> | No | Matching empty state loaders for dataLoaders | | defaultDataLoader | string | No | Default data loader key for the widget |

Common Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | loadingDelay | number | 2000 | Delay (ms) before loading data | | theme | 'light' \| 'dark' | 'light' | Initial theme | | autoLoad | boolean | true | Auto-load data on mount |

createMockData

createMockData<T>(fullData: T, config?: MockDataConfig<T>): MockData<T>

Creates type-safe mock data with automatic empty state generation.

Config Options:

• emptyData: Explicit empty state data
• emptyTransform: Function to derive empty state from full data
• If neither provided, generates empty object automatically

Mock OpenAI API

The DevContainer automatically mocks the window.openai API with these methods:

window.openai = {
  callTool: async (name, args) => { /* mocked */ },
  sendFollowUpMessage: async ({ prompt }) => { /* mocked */ },
  openExternal: ({ href }) => { /* mocked */ },
  setWidgetState: (state) => { /* mocked */ },
  // Plus all OpenAiGlobals properties
  theme: 'light' | 'dark',
  toolOutput: any,
  toolResponseMetadata: any, // Server _meta field (v1.2.0+)
  locale: string,
  maxHeight: number,
  userAgent: { device: { type }, capabilities: { hover, touch } },
  // DevTools-specific (v1.1.0+)
  widgetState: 'loading' | 'data' | 'empty' | 'error' // Current dev tool state
}

🎮 Interactive Controls

Toolbar Features

• State Controls: Switch between Loading, Instant Data, Delayed Data, Empty, and Error states
• Theme Toggle: Switch between light and dark themes
• Device Simulation: Test desktop, tablet, and mobile viewports
• Debug Border: Toggle visual boundary indicators
• Collapsible UI: Hide/show dev tools with a single click

💡 Common Patterns

Testing Loading States

<DevContainer
  loadingDelay={5000} // 5 second delay
  dataLoader={async () => {
    // Simulate slow API
    await new Promise(resolve => setTimeout(resolve, 2000));
    return { data: 'loaded' };
  }}
>
  <App />
</DevContainer>

Testing Empty States

<DevContainer
  emptyDataLoader={() => {
    // Return widget-specific empty state
    return {
      type: 'search-results',
      properties: [],
      searchInfo: { totalResults: 0, location: 'Sydney, NSW' }
    };
  }}
  dataLoader={async () => {
    // Regular data when not in empty state
    return await fetchMockData();
  }}
>
  <SearchWidget />
</DevContainer>

Testing Error States

<DevContainer
  dataLoader={() => {
    // Return error data
    return { error: 'Something went wrong' };
  }}
>
  <App />
</DevContainer>

Custom Mock Data

// mockData.ts
export const mockSearchResults = {
  type: 'search-results',
  items: [
    { id: 1, title: 'Result 1' },
    { id: 2, title: 'Result 2' }
  ]
};

// App.tsx
import { mockSearchResults } from './mockData';

<DevContainer
  dataLoader={() => mockSearchResults}
>
  <SearchWidget />
</DevContainer>

🏗 Architecture

The DevContainer follows these principles:

1. Zero Widget Contamination - Your widget code contains no dev-specific logic
2. Production Parity - Uses the same APIs as production ChatGPT Apps
3. External Debugging - All debug overlays are applied from outside the widget
4. Type Safety - Full TypeScript support with AINativeKit types
5. Clean Separation - Dev tools are never included in production builds

🔧 Development

Building the Package

npm run build

Development Mode

npm run dev

Type Checking

npm run type-check

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Jake Lin

🔗 Links

• GitHub Repository
• NPM Package
• AINativeKit - ChatGPT Apps SDK UI
• ChatGPT Apps Documentation

🙏 Acknowledgments

Built with ❤️ for the ChatGPT app developer community. This tool helps developers build and test ChatGPT Apps using the ChatGPT Apps SDK, making development faster and more enjoyable.