Repost for VS Code

Build versioned webhook contracts with a Prisma-style schema workflow. The Repost extension gives you first-class editing for .repost files while the Repost CLI scaffolds your schema, creates migrations, generates a type-safe client, and deploys your contracts. Descriptions written in the schema become SDK hover documentation and customer-facing Event Catalog content.

Start a schema project

Install the Repost CLI from npm:

npm install -g @repost/cli

Or use the macOS/Linux install script:

curl -fsSL https://releases.repost.sh/cli/install.sh | sh

Then initialize Repost in your project:

repost schema init
npm install @repost/client

repost schema init creates repost/schema.repost with a working starter schema. Open any .repost file in VS Code and the extension activates automatically.

Organize schemas by responsibility

schema.repost is a convenient starting point. For application schemas, the recommended architecture is a repost/schema/ directory with focused files:

repost/
|-- schema/
|   |-- config.repost
|   |-- enum-account-status.repost
|   |-- model-account.repost
|   |-- type-account.repost
|   `-- event-account-created.repost
`-- migrations/

The CLI and extension load every .repost file in that directory as one schema. Definitions can reference each other across files without imports, so models, enums, event catalogs, and individual events can stay small and purpose-specific.

Choose one layout: either repost/schema.repost or repost/schema/*.repost. After moving the starter definitions into focused files, remove repost/schema.repost; keeping both layouts is an error.

Create the initial migration after organizing the schema:

repost schema migrate dev --name init

Define contracts across files

For example, an account event can keep its catalog, payload, and event envelope in separate files.

repost/schema/type-account.repost:

type Account {
  created
}

repost/schema/model-account.repost:

/// Account state captured when the event was emitted
model Account {
  id       String
  openedAt DateTime @description("Time the account became available for transactions")
}

repost/schema/event-account-created.repost:

event AccountCreated {
  type      @type(Account.created)
  data      Account
  timestamp DateTime

  @description(`Emitted after account onboarding and required compliance checks complete.

**Use this event to**
- Provision the account in downstream systems
- Start welcome and onboarding workflows
- Record when the account became available for transactions`)
}

If you already use Prisma, the workflow will feel familiar: edit a declarative schema, generate a client, and commit reviewable migrations.

Document the contract once

Schema descriptions are generated with the contract instead of being discarded as source-only comments:

• Add /// above a model or field to generate TypeScript JSDoc and JSON Schema descriptions. SDK users see that context in autocomplete and hover details; webhook consumers see the same field descriptions in the Event Catalog.
• Add /// above a type-catalog member to provide the default event summary and JSDoc for its generated webhook method.
• Use @description("...") on a model or field when you want an explicit description attribute. It takes precedence over a nearby /// comment and is emitted to both JSDoc and generated schema documentation.
• Use the multiline backtick form of @description on an event for long-form event documentation. It becomes the generated webhook method's JSDoc and the event description deployed to the customer-facing Event Catalog, overriding the catalog member's /// summary.

repost schema migrate dev regenerates the client and schemas.json with this documentation. repost schema migrate deploy publishes the event and payload descriptions with the contract. SDK guidance and customer documentation stay synchronized because both come from the same versioned schema.

Document payload fields on their model definitions. Descriptions attached to the fixed type, data, or timestamp envelope fields are not emitted.

Work with the schema in your editor

• Read contracts quickly. Syntax highlighting covers schema blocks, field types, attributes, comments, strings, and Markdown inside multiline event descriptions, including escaped inline backticks.
• Catch invalid changes immediately. Live diagnostics report parser and schema validation errors as you type, including errors that involve sibling .repost files.
• Write with context. Completion suggests block keywords, field types, attributes, catalog members, and multiline description snippets where they are valid.
• Navigate larger schemas. Go to Definition resolves models, enums, type catalogs, and catalog members across sibling schema files. Document symbols populate the Outline and breadcrumbs for the current file.
• Keep diffs consistent. Format Document applies the canonical schema layout while preserving the contents of multiline Markdown descriptions.

Ship a schema change

Create a migration after editing your schema:

repost schema migrate dev --name add_account_events

The command records the contract change under repost/migrations/ and regenerates the default client in node_modules/.repost/client.

Create a Repost account and use the Repost dashboard to create an Environment. Copy its publish API key when it is shown and add it to the .env file created by repost schema init:

REPOST_SEND_API_KEY="rp_..."

Commit the schema and migration together. Sign in to your Repost account from the CLI, then deploy the committed migration history to the Environment:

repost auth login
repost schema migrate deploy

The deployed contract now appears in Repost with its generated event and payload documentation. The installed @repost/client package re-exports the generated code, and uses the Environment's publish API key when your application sends a webhook:

import { createRepostClient } from "@repost/client";

const repost = createRepostClient();

await repost.webhooks.account.created({
  customerId: "cus_123",
  data: account,
});

Run repost schema --help to discover validation, formatting, generation, migration, deployment, and CI commands from your installed CLI.

Requirements

• VS Code 1.85 or newer
• The Repost CLI, installed separately, for schema initialization, validation, generation, migrations, and deployment

For extension support, contact hello@repost.sh.

License

Apache-2.0. The bundled repost-schema engine is derived from Prisma's psl crates (Apache-2.0).