{"id":32786823,"url":"https://github.com/filippofilip95/react-openai-apps-sdk","last_synced_at":"2026-05-09T05:07:17.271Z","repository":{"id":321422232,"uuid":"1085783372","full_name":"filippofilip95/react-openai-apps-sdk","owner":"filippofilip95","description":"React hooks and devtools for OpenAI Apps SDK","archived":false,"fork":false,"pushed_at":"2025-12-15T13:59:27.000Z","size":90,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-18T17:38:35.297Z","etag":null,"topics":["apps-sdk","chatgpt","debugging","developer-tools","devtools","openai","react","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/filippofilip95/react-openai-devtools#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filippofilip95.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-29T14:03:40.000Z","updated_at":"2025-12-15T13:59:31.000Z","dependencies_parsed_at":"2025-10-29T21:29:04.942Z","dependency_job_id":null,"html_url":"https://github.com/filippofilip95/react-openai-apps-sdk","commit_stats":null,"previous_names":["filippofilip95/react-openai-devtools","filippofilip95/react-openai-apps-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/filippofilip95/react-openai-apps-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippofilip95%2Freact-openai-apps-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippofilip95%2Freact-openai-apps-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippofilip95%2Freact-openai-apps-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippofilip95%2Freact-openai-apps-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filippofilip95","download_url":"https://codeload.github.com/filippofilip95/react-openai-apps-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippofilip95%2Freact-openai-apps-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32807862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apps-sdk","chatgpt","debugging","developer-tools","devtools","openai","react","typescript"],"created_at":"2025-11-05T05:01:46.816Z","updated_at":"2026-05-09T05:07:17.265Z","avatar_url":"https://github.com/filippofilip95.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React OpenAI Apps SDK\n\n\u003e React hooks and devtools for OpenAI Apps SDK\n\n[![npm version](https://img.shields.io/npm/v/react-openai-apps-sdk)](https://www.npmjs.com/package/react-openai-apps-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n**React OpenAI Apps SDK** provides React hooks and DevTools for building ChatGPT widgets with OpenAI Apps SDK. Access `window.openai` globals through hooks, mock state for local development, and debug with a floating toolbar - toggle themes, change display modes, and inspect state in real-time.\n\n🎨 **Toggle theme** (light/dark) • 📐 **Change display mode** (inline/fullscreen/pip) • 📏 **Adjust height** • 🧪 **Mock `window.openai`** for local development\n\nBased on [OpenAI Apps SDK custom UX guide](https://developers.openai.com/apps-sdk/build/custom-ux) and [official examples](https://github.com/openai/openai-apps-sdk-examples).\n\n## Quick Start\n\n**Install:**\n\n```bash\nnpm install react-openai-apps-sdk\n```\n\n**Use:**\n\n```tsx\nimport { OpenAIDevTools, SafeArea, useOpenAIGlobal } from 'react-openai-apps-sdk';\n\nfunction MyWidget() {\n  const theme = useOpenAIGlobal('theme');\n\n  return (\n    \u003c\u003e\n      \u003cSafeArea\u003e\n        \u003cdiv className={theme === 'dark' ? 'dark' : 'light'}\u003e\n          Your widget content\n        \u003c/div\u003e\n      \u003c/SafeArea\u003e\n\n      \u003cOpenAIDevTools /\u003e\n    \u003c/\u003e\n  );\n}\n```\n\nThat's it! In development, you'll see a floating button. In production, it's automatically removed.\n\n## Features\n\n- ⚡ **Zero config** - Drop in and start debugging\n- 🎯 **Non-invasive** - Works with real ChatGPT without conflicts\n- ⌨️ **Keyboard shortcuts** - `E` for expand, `T` for theme\n- 📦 **Tree-shakeable** - Auto-removed in production builds\n- 🔌 **Framework-aware** - Based on OpenAI's official examples\n- 📱 **SafeArea component** - Automatically respect mobile notches and system UI\n\n## Keyboard Shortcuts\n\n- **E** - Toggle display mode (inline ↔ fullscreen)\n- **T** - Toggle theme (light ↔ dark)\n\n## Documentation\n\n- **[API Reference](./API.md)** - Complete API docs with all props and types\n- **[Examples](./EXAMPLES.md)** - Real-world usage examples and patterns\n- **[Contributing](./CONTRIBUTING.md)** - Development setup and guidelines\n\n## Common Use Cases\n\n### Respect Safe Areas (Mobile Notches, System UI)\n\n```tsx\nimport { SafeArea } from 'react-openai-apps-sdk';\n\n\u003cSafeArea fallbackHeight={600}\u003e\n  \u003cYourWidget /\u003e\n\u003c/SafeArea\u003e\n```\n\n### Get Tool Output\n\n```tsx\nconst toolOutput = useOpenAIGlobal('toolOutput');\n```\n\n### Check Display Mode\n\n```tsx\nconst displayMode = useOpenAIGlobal('displayMode');\nconst isFullscreen = displayMode === 'fullscreen';\n```\n\n### Call Tools (with error handling)\n\n```tsx\nconst { callTool, sendFollowUpMessage } = useOpenAIActions();\n\n// Call a tool with built-in error handling\nconst { success, data } = await callTool({\n  name: 'my_tool',\n  args: { arg: 'value' },\n  onError: (error) =\u003e console.error('Tool call failed:', error),\n});\n\n// Send follow-up message\nawait sendFollowUpMessage({\n  prompt: 'Here is the result...',\n  onSuccess: () =\u003e console.log('Message sent!'),\n});\n```\n\n### Custom Mock for Testing\n\n```tsx\n\u003cOpenAIDevTools\n  mockConfig={{\n    theme: 'dark',\n    toolOutput: { /* test data */ }\n  }}\n/\u003e\n```\n\n[See more examples →](./EXAMPLES.md)\n\n## How It Works\n\n### In ChatGPT (Production)\n\n1. ChatGPT provides `window.openai`\n2. DevTools detect real environment\n3. Toolbar shows current settings (read-only)\n4. Your widget uses real data\n\n### In Local Development\n\n1. `window.openai` doesn't exist\n2. DevTools create a mock\n3. Toolbar controls the mock state\n4. Your widget uses mock as if it's real\n\n### In Production Builds\n\n- DevTools automatically removed (tree-shaken)\n- Hooks still work (access real `window.openai`)\n- Zero bundle size impact\n\n**Production Debugging**: Enable DevTools in production ChatGPT for debugging:\n\n```bash\n# Build with DevTools enabled (read-only inspector)\nVITE_ENABLE_OPENAI_DEVTOOLS=true pnpm build\n```\n\nThis allows you to inspect `toolOutput`, `widgetState`, and other globals in production ChatGPT without creating mocks. The DevTools become a read-only inspector.\n\n## Comparison\n\n| Feature | Manual Setup | This Library |\n|---------|--------------|--------------|\n| Setup | Wrap entire app | Drop-in component |\n| Theme toggle | Code changes | One click |\n| Display mode | Code changes | One click |\n| Production | Manual guard | Auto tree-shaken |\n| ChatGPT compatible | May conflict | ✅ Yes |\n\n## FAQ\n\n**Does this work in real ChatGPT?**\nYes! It detects the real environment and doesn't interfere.\n\n**Does it increase bundle size?**\nNo. It's automatically removed in production builds.\n\n**Can I use without React?**\nThe UI is React-only, but core utilities (`createMockOpenAI`, `updateMockState`) work in any JS environment.\n\n## Links\n\n- [npm Package](https://www.npmjs.com/package/react-openai-apps-sdk)\n- [GitHub Repository](https://github.com/filippofilip95/react-openai-apps-sdk)\n- [OpenAI Apps SDK Docs](https://developers.openai.com/apps-sdk)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n\n## License\n\nMIT © [Filip Papranec](https://github.com/filippofilip95)\n\n---\n\n**Built by** [Filip Papranec](https://github.com/filippofilip95) **with** [Claude Code](https://claude.ai/code)\n\n**Inspired by**:\n- [React Query DevTools](https://tanstack.com/query/latest/docs/framework/react/devtools)\n- [OpenAI Apps SDK Examples](https://developers.openai.com/apps-sdk/build/custom-ux)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilippofilip95%2Freact-openai-apps-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilippofilip95%2Freact-openai-apps-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilippofilip95%2Freact-openai-apps-sdk/lists"}