The @gadgetinc/react-chatgpt-apps package provides wrapper components that allow you to communicate with your Gadget backend from a ChatGPT app's frontend widgets running inside ChatGPT.
@gadgetinc/react-chatgpt-apps is a React library for connecting ChatGPT apps to Gadget backend applications. It provides:
A <Provider> component that automatically authenticates your ChatGPT app with your Gadget backend
Easy integration with @gadgetinc/react hooks for reading and writing data
Automatic token management using OpenAI's and Gadget's authentication system
When building a ChatGPT app that needs to interact with a Gadget backend, this library handles all the authentication complexity for you, allowing your React components to focus on building great user experiences.
Installation
For Gadget apps that have a ChatGPT app connection, the @gadgetinc/react-chatgpt-apps package is automatically installed.
If you need to install the package manually, you can do so with yarn:
terminal
yarn add @gadgetinc/react-chatgpt-apps
Package manager support
Gadget apps use yarn as the package manager.
If you are adding @gadgetinc/react-chatgpt-apps to a non-Gadget app, you can use the package manager of your choice.
Setup
To use this library, wrap your ChatGPT app's React components in the Provider component from this package. The Provider automatically handles authentication with your Gadget backend using OpenAI's authentication system.
The best place to wrap your ChatGPT app's React components is in the web/chatgpt-widgets/root.tsx, which is a wrapper component that vite-plugin-chatgpt-widgets wraps all your ChatGPT widgets within.
web/chatgpt-widgets/root.jsx
React
// import the Provider component from this package
import { Provider } from "@gadgetinc/react-chatgpt-apps";
// import an instance of the Gadget API client from your app, usually in web/api.ts
import { api } from "../api";
function Root(props: { children: React.ReactNode }) {
return <Provider api={api}>{props.children}</Provider>;
}
export default Root;
// import the Provider component from this package
import { Provider } from "@gadgetinc/react-chatgpt-apps";
// import an instance of the Gadget API client from your app, usually in web/api.ts
import { api } from "../api";
function Root(props: { children: React.ReactNode }) {
return <Provider api={api}>{props.children}</Provider>;
}
export default Root;
Then, you must add an MCP tool call to your ChatGPT app's MCP server to allow fetching the auth token client side:
api/mcp.js
JavaScript
// gadget-specific tool for bootstrapping session auth within ChatGPT widgets
// don't remove this if you are using the `api` object client side in your widget React code!
mcpServer.registerTool(
"__getGadgetAuthTokenV1",
{
title: "Get the gadget auth token",
description:
"Gets the gadget auth token. Should never be called by LLMs or ChatGPT -- only used for internal auth machinery.",
_meta: {
// ensure widgets can invoke this tool to get the token
"openai/widgetAccessible": true,
},
},
async () => {
if (!request.headers["authorization"]) {
return {
structuredContent: {
token: null,
error: "no token found",
},
content: [],
};
}
const [scheme, token] = request.headers["authorization"].split(" ", 2);
if (scheme !== "Bearer") {
return {
structuredContent: {
token: null,
error: "incorrect token scheme",
},
content: [],
};
}
return {
structuredContent: {
token,
scheme,
},
content: [],
};
}
);
// gadget-specific tool for bootstrapping session auth within ChatGPT widgets
// don't remove this if you are using the `api` object client side in your widget React code!
mcpServer.registerTool(
"__getGadgetAuthTokenV1",
{
title: "Get the gadget auth token",
description:
"Gets the gadget auth token. Should never be called by LLMs or ChatGPT -- only used for internal auth machinery.",
_meta: {
// ensure widgets can invoke this tool to get the token
"openai/widgetAccessible": true,
},
},
async () => {
if (!request.headers["authorization"]) {
return {
structuredContent: {
token: null,
error: "no token found",
},
content: [],
};
}
const [scheme, token] = request.headers["authorization"].split(" ", 2);
if (scheme !== "Bearer") {
return {
structuredContent: {
token: null,
error: "incorrect token scheme",
},
content: [],
};
}
return {
structuredContent: {
token,
scheme,
},
content: [],
};
}
);
That's it! The Provider component will:
Automatically fetch the authentication token from OpenAI when your app loads
Configure your Gadget API client to use this token for all requests
Ensure all API calls wait for authentication to be ready before proceeding
Using without authentication
If you don't need authentication for your ChatGPT widgets such that they are safe to be world readable, you can disable authentication in the provider by setting the authenticate prop to false:
web/chatgpt-widgets/root.jsx
JavaScript
import { Provider } from "@gadgetinc/react-chatgpt-apps";
import { api } from "../api";
function Root(props: { children: React.ReactNode }) {
return (
<Provider api={api} authenticate={false}>
{props.children}
</Provider>
);
}
export default Root;
import { Provider } from "@gadgetinc/react-chatgpt-apps";
import { api } from "../api";
function Root(props: { children: React.ReactNode }) {
return (
<Provider api={api} authenticate={false}>
{props.children}
</Provider>
);
}
export default Root;
Reference
Provider
A Provider component that wraps your ChatGPT app's widgets to authenticate the API client and generate a session token.
Props
api: Client - The Gadget API client to use for the extension.
authenticate: boolean - Whether to authenticate the API client. Defaults to true.