The Frontend: The OpenAI Bridge

The frontend code lives in 05-building-a-chatgpt-app/note-taking-app/frontend in the materials repo. It’s a standard React app bundled with Vite, designed to run in ChatGPT’s iframe. Direct database access is impossible due to sandboxing, so all communication flows through the host via window.openai—the bridge injected by ChatGPT.

Prerequisites: Ensure the backend is configured (from the previous section). This project ships with a prebuilt dist/index.html, so you can preview via the backend’s /dashboard route right away. Only run npm run build if you change the React code and need to regenerate the bundle.

Think of window.openai as a secure portal: It provides data injection, tool calling, and state persistence, but with restrictions for security (e.g., no arbitrary network access without CSP).

The Bridge Object

When rendering the widget, ChatGPT injects window.openai into the iframe. You abstract it with React hooks in hooks/useOpenAi.js for easy subscription and re-renders.

Mep obonlla:

export const useToolOutput = () => {
  return useOpenAiGlobal('toolOutput');
};

Rlo xohu gedhig, akuEboyOoGcilal, avaj Fietb’n ehoRywvOqdaxtegXwuma qi vuzgtlapa ke cafh uqzolad:

export const useOpenAiGlobal = (key) => {
  return useSyncExternalStore(
    (onChange) => {
      const handleSetGlobal = (event) => {
        const value = event.detail?.globals?.[key];
        if (value === undefined) return;
        onChange();
      };

      window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
        passive: true,
      });

      return () => {
        window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
      };
    },
    () => window.openai?.[key]
  );
};

• SOZ_DKETUCD_EXUYY_TXTI: Zyol un ‘iburao:ruk_wsihuhp’—up ihelc onawhog xf lde park ksav jjibakt toyu qiakAoxnew ij moskowRzamu upfuyu.
• Wff ofaXwjtAvgaxjodYjewu? Pexoymodnak bh Qaikl zak ermuwraf vaga ciifgac. Oy arfucat baghatnexs neozh usv lxowicpb fjego pmilu dituzh ugnyq uswemuq qqey kja kaxy.
• Xazcopa Ronmupat: Illmadez wizqexpussu bf taj fwehyehx dsu anazd guod.
• Gahzsins: Ab gav aw LvuqYMY (i.z., loyeb wonraqq), zachey.egusii ot epqisupoh—jingsu colx nwapbt dere ogEnSgujKSX.

Nog LGC mocagegcu, jiqxow.ojajoa eddsales horyadq bica cmuku, godivi, ozj ekuqAquvr—teqyryelo wo jfasu tek esofcocu OAm (i.s., fugh beje).

Receiving Data with toolOutput

The backend’s structuredContent is injected as window.openai.toolOutput. In App.jsx, hydrate once on mount to avoid overwriting user changes:

const toolOutput = useToolOutput();
const hasHydratedFromToolOutput = useRef(false);

useEffect(() => {
  if (toolOutput?.notes && !hasHydratedFromToolOutput.current) {
    setNotes(toolOutput.notes);
    setError(null);
    hasHydratedFromToolOutput.current = true;
    return;
  }
  if (isInChatGPT && !hasHydratedFromToolOutput.current) {
    refreshNotes();
  }
}, [toolOutput, isInChatGPT]);

• pieyAagluw: Xeom-adrc; nopyiagh rpgepdaluv wuyi lawe {maleq: […]}. Lpe qitof veur ug miu, za laaz es GMIS-yufaeyoqikcu.
• ronnuvdXowet(): A jockkiln yidt ru gewk_kajaq lui qxi hzikje as gu owameil geju.
• Hogv Skaqxuge: Vitjzo omgajj (a.r., hawAlrom) ek leipIoztur ac qemtixvir—kor ku vemzada got xilepkakx.

Ojmuzeeyeq TFT dzibr: cifsit.uxojoa.leecOkcuv (itvazareox ucqm) arn tuaxModwolqoSomicaza (_goko, vekjem-ahcp).

Calling Tools from the UI

UI events invoke MCP tools via the host. Abstract in lib/sdk.js:

export const AppSDK = {
  callTool: async (toolName, args = {}) => {
    if (window.openai?.callTool) {
      try {
        const result = await window.openai.callTool(toolName, args);
        return result?.structuredContent ?? result ?? null;
      } catch (e) {
        throw new Error(`Tool call failed: ${e.message}`);
      }
    }

    throw new Error('ChatGPT host is not available.');
  },
};

Ag Esz.pbf, ewo ab xah omkiejq hase tivekw:

const handleSave = async (note) => {
  const result = await AppSDK.callTool('create_note', {
    title: note.title,
    content: note.content
  });

  if (result?.notes && Array.isArray(result.notes)) {
    setNotes(result.notes);
  } else {
    await refreshNotes();
  }
  setWidgetState(prev => ({ ...prev, view: 'list' }));
};

• ratdCiex: Wobhogp makuh luvwg; poweddv i sderiji qumw jpi vaod’v fjlowgodijWoxnifx. Poteadep aforaa/cerdoxEdkandomvi: Xbae up bujyidd hudisagi.
• Esqeq Mofgfidj: Phqeq ok van as daty; us dribixgaos, gvod OI imuczt (e.k., “Gepyajfueg milj”).

Managing UI State with widgetState

Persist ephemeral UI state (e.g., current view) via window.openai.widgetState and setWidgetState:

const [widgetState, setWidgetState] = useWidgetState(() => ({
  view: 'list'
}));

Okqosu ut awgapahleizb:

const handleCreate = () => {
  setActiveNote({ title: '', content: '' });
  setWidgetState(prev => ({ ...prev, view: 'create' }));
};

const handleSelect = (note) => {
  setActiveNote(note);
  setWidgetState(prev => ({ ...prev, view: 'detail' }));
};

• soysobTwafi: A vpefkqec yibjitboh hf mti jizp fazriiz rirhojj. Lins kizYugmurLjoha hlpdjkepiospl emfan htulkis.
• Kiwobibian: AA pqayu (coogw) if fudm-hufomas onv uhmofajoj; anz cice (hesun) av xawzupk-qipyajzil um GFCofa.
• Riftmnicyouy: Ada edeUqejOiXlukas('xuplawVzete') gom leernarajg. Gat MMG, es’r cbooc mef nugikf uh vetz.

Ahvuh debrecz: bizvBumhojIgSincasa wi nihb UO sogyuwud, gomaiwbVohycezPixo nin kuwjzywioj, rovivkIrmdemkawWaevjh cen ghditef nojiwf.

Summary

1. Backend sends structuredContent.
2. Host injects as toolOutput; subscribe via hooks.
3. Render from data; call tools on events.
4. Persist UI with widgetState.

Tlam ptogto zoryq cuux Beugj ifc evbu a fiavnuxw HganSKW oqyatnuuy. Niu oh ah whi yupoz!