Build one useful interaction: a reading list, a shared task board, your own research notebook. Your frontend owns the screen; app-sdk supplies login, connections and safe editing. People keep their data in their Pod.
Start a new app in sempods-apps-template, or integrate the SDK into an existing React app with the quickstart. Their setup instructions own the dependencies; keep the matching exact SDK versions and lockfile.
The template reads the installed
node_modules/@sempods/app-sdk/docs/ai-app-builder.md; give your assistant the
same entry in a custom project. Describe the first useful interaction in your
own words. You do not need to prescribe a layout or component library: the
AI guide asks the
assistant to make and inspect a coherent first design.
To try unreleased SDK changes, use the quickstart's packed SDK archives. To make it installable, add the PWA setup. Use a dedicated test context and synthetic data; follow local or hosted Pod testing for setup.
The API table maps every job to its hook or component and entry; the working task screen uses them together. For the first hour you need:
createBrowserRuntime,SempodsProvider,AppAccessandTargetScreen;fieldsandtext(withtrim: true) for your data;useListwith<LoadNotice {...list} />,useCreation, and oneuseFieldUpdateper list withmutate.for(item)per row;UpdateNoticefor every write's outcome, andUnresolvedNoticesfor recovery when the corresponding row disappears.
- Connected is not selected. Grant access, then explicitly choose a context. Empty selection never means “all”; the Pod authorizes each operation.
- One tab per app. A second tab of the same app shows that it is open elsewhere; use a private window for a second person. A reload keeps the session and the last chosen context while it is readable. Change sharing grants another context.
- Unconfirmed is not failed. A lost answer may hide a completed write. Use the SDK's comparison and acknowledgement UI; do not auto-retry or invent a fresh IRI for uncertain creation. Recovery details.
- Local and deployed identities differ. Local HTTP uses the quickstart's
dynamic identity and
loopback-httpoption. Deployment uses an explicitdid:webidentity, matching HTTPS callback host/port/path, and a route that serves the app. No client secret is needed, and a conforming Pod needs no DID document. If the Pod rejects the app before or at consent, it may require a DID document and an allow-listed host. Domain setup and Netlify example. - A frontend cannot hide secrets.
VITE_*values enter the public bundle. Leave session tokens to the SDK; keep hosting/provider keys out of source, logs and AI prompts. UI language does not change RDF text language.
Run the app build and the end-to-end walkthrough. Inspect the actual screen at phone and desktop widths, including empty, populated and recovery states. Keep the app's purpose, visual choices and data mapping in its notes; distinguish browser-fixture checks from live Pod and installed-device evidence.