SDK entry points - Reintersect Developers

@reintersect/sdk is one package with several entry points. Import only the ones you use, because each is tree-shaken separately. Effect is an optional peer dependency, so install effect and @effect/platform only if you import an Effect entry point.

npm install @reintersect/sdk

pnpm add @reintersect/sdk

bun add @reintersect/sdk

The current version is 0.4.0. The CLI (reintersect) is a bin in the same package, and it loads the optional peer dependencies esbuild and miniflare for build and dev.

Entry points

Entry point	Use it for
`@reintersect/sdk`	Calling Reintersect from outside a handler, `renderPayload`, document JSX, the member API client and app streams
`@reintersect/sdk/app`	Defining blocks, actions, references, events, commands, message actions and routes, and composing the app
`@reintersect/sdk/components`	The block component catalog
`@reintersect/sdk/recipes`	Ready-made block factories
`@reintersect/sdk/mcp`	Verifying Reintersect-signed tokens in an MCP server
`@reintersect/sdk/testing`	A fake Reintersect host for Vitest or `bun test`
`@reintersect/sdk/effect`	The Effect clients
`@reintersect/sdk/effect/app`	Effect versions of the app pieces, with Effect Schema and generator handlers
`@reintersect/sdk/effect/recipes`	The recipe factories for Effect apps
`@reintersect/sdk/effect/testing`	The fake host as an Effect service for `@effect/vitest`
`@reintersect/sdk/jsx-runtime`, `/jsx-dev-runtime`	The JSX runtime. The compiler imports it, so you never need to.
`@reintersect/sdk/effect/jsx-runtime`, `/effect/jsx-dev-runtime`	The JSX runtime for components that return an `Effect`.

`@reintersect/sdk`

Export	Description
`createReintersectClient(app, options)`	A client acting as your app for one install, typed by the app’s scopes and blocks. See Client.
`createReintersectClient({ apiKey })`	The member API client: acts as a member with an API key.
`renderPayload(content)`	Renders JSX or a document to the exact JSON the API accepts.
`createReintersectStream(options)`	Posts to a circle app stream URL.
Document JSX	`Document`, `Paragraph`, `Heading`, `Blockquote`, `Quote`, `UnorderedList`, `OrderedList`, `ListItem`, `CodeBlock`, `HorizontalRule`, `Bold`, `Italic`, `Strike`, `Underline`, `Code`, `Link`, `Mention`, `Emoji`, `CustomEmoji`, `HardBreak`, `Image`, `File`, `Video`, `VideoMoment`, `Table`, `TableRow`, `TableHeader`, `TableCell`, `Reference`, `Show`, `For`, `Fragment`
Errors	The SDK, document and app API error classes, such as `ReintersectAppBlockVersionConflictError`.

`@reintersect/sdk/app`

Export	Description
`createReintersectApp(options)`	Starts an app. See Composing an app.
`defineBlock(options)`	Defines a block type. See Blocks.
`defineAction(name, options, handler)`	Defines an action. See State and actions.
`choice(values, options?)`	Declares a viewer input. See Votes and tallies. With a `{ value: "Label" }` record it’s a labelled command option instead. See Option schemas.
`member(schema)`, `circle(schema)`, `appObject(kind, schema)`	Mark a Zod or ArkType schema as a command option picker. See Pickers.
`memberOption`, `circleOption`, `appObjectOption(kind)`	The picker metadata, for schema libraries that add metadata themselves, such as Valibot’s `v.metadata()`.
`optional(schema)`	Makes an entry of a record of option schemas optional. See Order.
`defineReference(kind, options)`	Defines a reference kind. See References.
`defineEvent(name, options?, handler)`	Handles a lifecycle event. See Events.
`defineCommand(name, options, handler)`	Adds a slash command to the chat composer. See Slash commands.
`defineMessageAction(id, options, handler)`	Adds an item to the message menu. See Message actions.
`defineRoute(options)`	Defines an HTTP route. See Routes.
`secret(options?)`	Declares a secret environment variable.
`log`	`log.info(message, fields?)` and `log.error(message, fields?)`; secrets aren’t loggable values.
`manifestOf(app, options?)`	Returns the manifest Reintersect derives from the app.
`toNodeHandler(app)`	Adapts `app.fetch` to a Node `http` request listener.
Errors	`ReintersectAppConfigurationError`, `ReintersectAppDeliveryInvalidError`, `ReintersectAppHandlerFailedError`, `ReintersectAppInstallTokenError`, `ReintersectAppPieceUnknownError`, `ReintersectAppProgressMismatchError`, `ReintersectAppSchemaRejectedError`, `ReintersectAppSignatureError`, `ReintersectAppViewInvalidError`
Types	`CommandContext`, `CommandOptions`, `CommandOptionsOf`, `MessageActionContext`, `MessageActionContextData`, `InvocationAnswer`, `InvocationProgress`, `ProgressOptions`, `InvocationSurface`, `InvocationRef`, `Defer`, `DeferOptions` and the other piece types.

The composed app has .addBlock, .addReference, .addEvent, .addCommand, .addMessageAction, .addRoute, .addMcp(handler, { auth }) and fetch(request, env?, ctx?).

`@reintersect/sdk/components`

The catalog components, listed on the catalog overview, plus the rich text components for Prose and Text. Inline code is InlineCode here, because Code is the code block component.

`@reintersect/sdk/recipes` and `@reintersect/sdk/effect/recipes`

The factories approval, poll, rsvp, checklist, deployment, incident, ticket and metricsPanel, plus each recipe’s view component, schemas, labels and helpers. See Recipes.

`@reintersect/sdk/mcp`

Export	Description
`verifyReintersectToken({ audience, appId?, issuer?, fetch? })`	Returns `(request, bearer?) => Promise<ReintersectAuthInfo \| undefined>`.
`ReintersectTokenInvalidError`	The tagged error behind a rejected token, with a `reason`.
Types	`McpAuth`, `McpHandler`, `McpFetchHandler`, `McpRequestExtra`, `ReintersectAuthInfo`, `ReintersectCaller`, `ReintersectTokenVerifier`, `VerifyReintersectTokenOptions`

To mount an MCP server on your app, call .addMcp on the app. See MCP servers.

`@reintersect/sdk/testing` and `@reintersect/sdk/effect/testing`

createTestHost(app, options?) on the Promise entry; makeTestHost(app, options?) and ReintersectTestHost (a service with ReintersectTestHost.layer(app, options?)) on the Effect entry. Both export textOf, findNodes, buttonsOf, buttonOf, treeFor, checkTree, expectTree, testViewer, TEST_SIGNING_SECRET, TREE_LIMITS and the test error classes. See Testing.

`@reintersect/sdk/effect` and `@reintersect/sdk/effect/app`

/effect exports the Effect member API client (Reintersect, ReintersectClient), the app client ReintersectAppClient.make(app, options), renderPayload and ReintersectStream. /effect/app exports createReintersectApp, defineBlock, defineAction, defineReference, defineEvent, defineCommand, defineMessageAction, defineRoute, choice, secret, provide, manifestOf, toNodeHandler, the ReintersectApp namespace (ReintersectApp.layer) and the app error classes. See the Effect guide.

JSX configuration

Blocks and documents use the automatic JSX transform with the SDK as the import source. Set it once in tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@reintersect/sdk",
    "strict": true
  }
}

Effect apps use the same setting, which already accepts components that return an Effect. You can also set the import source per file:

/** @jsxImportSource @reintersect/sdk */

There are no intrinsic elements: <div> is a type error, because blocks are built only from the catalog. Components may return JSX, a Promise of JSX, or, on the Effect entry, an Effect of JSX.

Schemas

Props, state, action args, action input, install config and environment values all take a schema. On the non-Effect entry points, a schema must implement both Standard Schema V1 and Standard JSON Schema V1. Reintersect validates values, and it also needs JSON Schema for forms, agent tools and the manifest.

Library	Minimum version	Notes
Zod	4.2	The default in templates and these docs.
ArkType	2.1.28	Object schemas sort their keys. See Order.
Valibot	1.x	Wrap each schema with `toStandardJsonSchema()` from `@valibot/to-json-schema`.
Effect Schema	Effect 3.x	Only on `@reintersect/sdk/effect/app`.

import { toStandardJsonSchema } from "@valibot/to-json-schema";
import * as v from "valibot";

const props = toStandardJsonSchema(v.object({ title: v.string() }));

Passing an unsupported schema is a type error with one of these messages:

Schema	Message
Effect Schema on a non-Effect entry	`Effect Schema values belong to the Effect entry: import from @reintersect/sdk/effect/app`
Valibot without the adapter	`Valibot schemas need JSON Schema support: wrap it with toStandardJsonSchema() from @valibot/to-json-schema`
A Standard Schema with no JSON Schema support	`This schema cannot produce JSON Schema (StandardJSONSchemaV1). Use zod >= 4.2, arktype >= 2.1.28, or valibot with toStandardJsonSchema()`
Anything else	`Expected a Standard Schema (zod, arktype, or valibot)`

State schemas must not transform

Reintersect stores block state as JSON and Standard Schema has no encode step, so a state schema’s input and output types must be the same. A transform such as parsing a string into a Date is a type error:

Block state is stored as JSON and Standard Schema has no encode step: the state schema must not transform values (its input and output types differ)

Keep dates as ISO strings in state and parse them where you use them. Effect Schema can transform state, because it encodes back to JSON before Reintersect stores it.

​Entry points

​@reintersect/sdk

​@reintersect/sdk/app

​@reintersect/sdk/components

​@reintersect/sdk/recipes and @reintersect/sdk/effect/recipes

​@reintersect/sdk/mcp

​@reintersect/sdk/testing and @reintersect/sdk/effect/testing

​@reintersect/sdk/effect and @reintersect/sdk/effect/app

​JSX configuration

​Schemas

​State schemas must not transform