Skip to content

About

TypeScript SDKs for sempods apps: portable client and browser app runtime

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

220 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

sempods TypeScript SDK

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.

Find your starting point

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.

Try the examples locally

Use Node 24.15 or newer and pnpm 11.1.2. From the repository root:

pnpm install --frozen-lockfile
pnpm dev:todo

Open 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.

Supported environments

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.

About

TypeScript SDKs for sempods apps: portable client and browser app runtime

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages