Reusable modules for apps and scripts that work with sempods data. Connect to a Pod, read Linked Data and edit it without losing someone else's changes. People keep their data in their Pod; your code supplies the interaction.
This repository develops and publishes three packages:
| Package | Use it for | Runs in |
|---|---|---|
| @sempods/client-sdk | Protocol requests, portable OAuth, field definitions and conditional editing | Browser or Node |
| @sempods/app-sdk | Login, durable browser sessions, target selection and authoring helpers | Browser, with optional React |
| @sempods/app-ui | UI components on React Aria and a theme contract, for Tailwind CSS 4 apps | Browser, React 19 |
app-sdk builds on client-sdk. Its root entry works without React;
@sempods/app-sdk/react adds components and hooks. app-ui adds shadcn/ui
components and adapters for SDK editors on top of app-sdk's React entry; app-sdk
itself stays free of a UI framework. The packages provide ESM and TypeScript
declarations. The examples demonstrate their public APIs and serve as
executable integration checks.
Starting a new app with a coding assistant? Use sempods-apps-template, the app-focused starting point built on these modules. Work in this repository when changing the SDK, its examples or documentation.
| I want to… | Start here |
|---|---|
| Choose a module | client-sdk or app-sdk |
| Create a new app with a coding assistant | Apps template; it reads the SDK's installed AI guide |
| Add the SDK to an existing React app | Complete quickstart, then the relevant authoring reference |
| Give a coding assistant the SDK's app-building rules | AI app-builder entry, also shipped in app-sdk |
| Use another UI framework | Headless authoring |
| Embed widgets in an existing host | Widget authoring |
| Read across a Pod without choosing a context | Pod reads and React overview |
| Write a Node script | Node example |
| Configure login or understand session recovery | Browser runtime |
| Upgrade an existing app | Migration and recovery |
| Contribute to the modules | Contributing, development checks and AGENTS.md |
The documentation map routes to optional guides by task. Build your own app explains the model; the hackathon reference is a checklist after setup. The vision and architecture decisions explain the package boundaries.
Use Node 24.15 or newer and pnpm 11.1.2. From the repository root:
pnpm install --frozen-lockfile
pnpm dev:todoOpen http://127.0.0.1:5173/ and connect a Pod with a test context. The
TODO example uses only the SDK's standard UI and the
@sempods/app-ui kit for its header and task screen.
The Node example uses the same field definitions.
The packages are published on npm under Apache-2.0 (documentation: CC BY 4.0; see NOTICE). Version 0.x may change APIs between minor versions. Automated checks cover installed packages and browser fixtures. Live-Pod, installed-device and independent app-author validation are separate evidence; see development checks.
For 0.8.0, see the release notes and upgrade instructions.
| Environment | Status in 0.8 |
|---|---|
| Node | 24.15 or newer (Node 24 LTS), ESM only (engines in every package). |
| Browser tab | Current browsers with IndexedDB and Web Locks. Automated browser checks run in Chromium. |
| React | 19, for @sempods/app-sdk/react (optional peer). |
| UI kit | Since 0.7: @sempods/app-ui with React 19 and Tailwind CSS 4.1 or newer. Its browser gate runs in Chromium and WebKit, and in Firefox on Linux CI. |
| Installed PWA (experimental) | Desktop Chromium and Android are expected to work; iOS/iPadOS home-screen apps are unverified. Login returns to the app in the same window and must land in the app's own storage. |
Support for installed apps is extended after device evidence. Until then, use a normal browser tab where an installed app cannot complete sign-in.
Explore sempods, its use cases and the protocol specification.