Skip to main content
This guide takes about ten minutes. At the end you have an app running on your machine, a block you can insert into a conversation, and a playground that shows the block the way members, share pages and agents see it. Using Effect? See Build with Effect.

Before you start

  • Node.js 22 or later (the templates use Node 24 in CI), or Bun 1.3 or later.
  • A Reintersect account. Any member can build apps; you don’t need to be an admin to develop one.

Create the app

1

Scaffold a project

Run the scaffolder and answer its prompts:
It asks for:Skip the prompts with flags, for example npm create reintersect@latest tasks -- --template next --schema arktype --yes:npm create reintersect@latest -- --help lists every flag and template.The project contains a Task block with a move action, a task reference with search, typed environment variables and install config, tests, a GitHub workflow that deploys with reintersect/deploy@v1, and an AGENTS.md with an SDK skill so coding agents follow the same conventions.
2

Sign in

The scaffolder offers to sign you in at the end. To do it later:
The CLI prints a link and a code. Open the link, check that the page shows the same code, and approve it. The CLI then stores a key for your workspace in ~/.config/reintersect/credentials.json.
3

Start the dev server

reintersect dev:
  1. Creates a personal development app in your workspace the first time it runs, with a development install only you can use.
  2. Syncs the manifest built from your code (blocks, references, actions, scopes and events) every time you save.
  3. Runs your app locally and opens a relay from Reintersect to it. Every delivery for your development install is replayed to your machine as the exact signed request production would send.
  4. Prints a playground link.
Hosted apps run locally in the same Workers runtime Reintersect uses in production (Miniflare). Self-hosted templates run in a local Node server the CLI starts. Put local values for your environment variables in .dev.vars.
4

Open the playground

The playground link opens your app’s playground in Reintersect. It renders each block with sample props in three modes:Click Start in the interactive view. The request goes through the relay to your machine, and the dev panel in your terminal shows the delivery.

Change the block

Open src/taskBlock.tsx. The scaffolded block looks like this (with Zod schemas from src/schemas.ts):
src/taskBlock.tsx
Change the Fact label, save, and the playground re-renders. Now try a mistake: add destructive: true to moveTask. TypeScript reports that the button needs a confirm prop, because Reintersect asks members to confirm destructive actions. The dialog’s button repeats the button’s label, and the button switches to the danger style:

Use it in a conversation

Open a conversation in your workspace, type / and pick Task. Reintersect shows a form for the block’s required props, then inserts it. A development install belongs to you alone: other members see its blocks with a “Dev” label, and only you can insert them or run their actions. Paste https://tasks.example.com/tasks/TASK-1 into a message too: the task reference resolves into a chip, and the card display shows the Task block.
Leave reintersect dev running while you test. When it stops, your development blocks keep their last tree, and clicking an action fails with an “offline” error until you start it again.

Test, check and deploy

Run the tests and the same checks CI runs:
reintersect check builds the app, renders every block with sample props, and reports problems the type checker can’t see, such as a tree over the size limit or a pattern for a domain you didn’t claim. Signed in, it also sends the rendered trees to Reintersect’s own validator. Then deploy a preview to your development app:
For production, deploy to an app by id. Create one in Settings → Developer → Apps (or use your development app’s id), then:
A hosted app uploads its bundle; a self-hosted app syncs its manifest and endpoint. A workspace admin can then install the app from its install link. For deploys from GitHub on every merge, see GitHub Action.

Next steps

How apps are composed

Blocks, references, events, commands and message actions are standalone pieces. Learn how they combine into one app.

Blocks

State, actions, viewer inputs, sections and forms.

Component catalog

Every component with its props, read-only behaviour and agent text.

References

Teach Reintersect your links.