← stitchkitDocumentation

Documentation

The guide walks through building an app with stitchkit, from the first contract to deployment. Every page is pulled straight from the repository at build time, so it never drifts from the source.

  • Getting startedstitchkit turns one contract into an HTTP API, MCP tools, AI-agent tools and a typed client. This page gets a working app running; the rest of the guide goes deep on each piece.
  • ContractsA contract describes a set of operations once — method, path, schemas, scope, which transports each is exposed on. From it stitchkit derives the HTTP route, the MCP tool, the agent tool and the typed
  • HTTP serverstitchkit serves contracts on Bun.serve() directly — no Hono, no Elysia, no Express. You bind a contract to handlers with implement(), then mount the result on createServer().
  • Typed clientFrom a contract, createClient builds a fully-typed client — one method per endpoint, arguments and result inferred from the schemas. There is no codegen step: the types come straight from the contract
  • Realtimestitchkit's realtime layer is Socket.IO — polling fallback, heartbeats, acks, a mature client. stitchkit does not ship its own WebSocket engine; it ships thin, typed wrappers over Socket.IO and a brid
  • Auth & errorsClient-side login/session operations may legitimately answer 401. Declare that policy with contract-owned matchers instead of path strings:
  • MCP & AI agentsThe application generated by bun create stitchkit includes a working stateless MCP endpoint and a separate bun run tools manifest command. Both are assembled from the same implemented project contract
  • CLIThe same contract and managed runtime tools that drive HTTP, MCP and agent surfaces can also drive a command-line program. createCli composes their commands with explicitly local binary commands in on
  • Multi-tenant / resource-scoped pathsA walkthrough of one mainstream scenario end-to-end: a SaaS API scoped by a path segment — /tenants/:tenantId/widgets/... — where the same tenantId gates access in auth and is injected into tool calls
  • ObservabilityA request reaches your app through one of two surfaces — an HTTP route or a tool call (MCP / agent). Observability is the same question on both: what happened, how long did it take, who made it, did i
  • Testing & deploymentstitchkit's own test suite runs on bun:test. The contract makes most of an API testable without a live socket.
  • Upgrading stitchkitWho must act: applications whose raw routes call parseBody on JSON larger than 1 MiB, and applications whose OAuth clients send /register or /token bodies larger than 64 KiB.
  • API referenceEvery public export of stitchkit, grouped by entrypoint. Each entry links to the guide page that explains it in context. Types are marked type; everything else is a value (a function, a class, a const
  • Agent composition without a second runtimeUse these pieces when an application wants the existing headless harness and a generic conversation view. An application with its own AI SDK loop keeps mountAgent; a product with custom message projec
  • Agent application runtime> Maturity: evolving. This surface is still finding its shape and may be > redefined in any minor release — always with a ### ⚠️ Breaking changes entry > and a migration section, never silently. If yo
  • Managed application kernel> Maturity: evolving. This surface is still finding its shape and may be > redefined in any minor release — always with a ### ⚠️ Breaking changes entry > and a migration section, never silently. The s
  • Application migration recipesThese recipes are the migration companion to the managed application kernel. Their canonical source is the packed-consumer fixture application-migration-recipes.ts: the consumer lane installs the pack
  • Project declaration> Maturity: evolving. This surface is still finding its shape and may be > redefined in any minor release — always with a ### ⚠️ Breaking changes entry > and a migration section, never silently.
  • Frontend integrationsThe official bun create stitchkit application uses Next.js with a separate Bun API. Stitchkit remains a Fetch-native backend and does not own frontend routing, SSR or HMR.
  • GeoIPstitchkit/geo is a server-only, evolving entrypoint for reading local GeoIP databases without making a database vendor part of the framework contract. It exposes a managed resolver, a peer-neutral rea
  • Keyboard layers and list zonesstitchkit/react/keyboard answers one question for a React screen: who gets this key? It is headless — three hooks and no component, no styles, no router. The application keeps its URL, its sections an
  • Live data — announcements, watched reads, keyspaces and the trust fenceFour things an application builds by hand the second time it needs them. stitchkit/live is evolving: it ships from its own entrypoint so that is visible rather than discovered in a minor.
  • Bounded commands and file guaranteesShortest working example: publish a file atomically, then run one bounded command.
  • Browser OAuth and Google OIDCStitchkit separates the browser's Authorization Code + PKCE transaction from the server's provider credential verification. The application still owns navigation, users, account matching and merge pol
  • Generic application primitivesstitchkit/primitives is an optional browser-safe leaf. It declares values and policies; it does not own a database, transaction, scheduler, durable queue, transport or document generator.
  • React Query policystitchkit/react contains policy adapters for TanStack Query. It does not own application queries, cache keys or authentication.
  • ReleaseA tab that outlives a release keeps running a bundle the server no longer serves. stitchkit/release makes the page follow the release it was built for: the server names its current frontend build, the
  • Optional process sandboxstitchkit/agent-runtime/sandbox is a server-only, evolving API. Existing coding tools and agent configuration retain their current behavior. A host explicitly creates a session and opts into createSan
  • Telegram screensstitchkit/telegram/screens turns a bot's menus into declared screens. A screen says what the chat should show — a message or several, with their buttons — and the runtime decides what to send, what to
  • Telegram botsstitchkit/telegram holds what the Bot API itself asks of every bot, with no bot library; stitchkit/application/grammy makes a grammY bot a set of application resources. Together they are what a bot is
  • Visitor trackingstitchkit/tracking is the browser half of visitor tracking — the outbox, the visit lease, the page-leave beacon, visible time, scroll milestones, declarative clicks, attribution — and stitchkit/tracki
  • VoiceA live voice conversation with an agent repeats the same mechanics in every application that has one: the reply is cut into sentences while the model is still writing it, each sentence is stripped dow