serve

Start a local development server that compiles your stream/aggregation and realm definitions, serves the HTTP API, and hot-reloads on file changes.

Usage

iwentsourcing serve <src...> [options]

Argument	Description
<src...>	One or more entry files that export your stream/aggregation definitions (see Entry File Format)

Entry File Format

Your entry file must export your stream runtime(s), aggregation runtime(s), and optionally seed data:

// src/state/export.ts
export { todoStream } from './todo/stream.js';
export { personalTodoAggregation } from './aggregation/personal-todo.js';
export { todoSeed } from './seed.js';

By default all named exports are processed. Use --variable to restrict to specific export names.

Options

Flag	Default	Description
-s, --storage <uri>	:memory:	Storage backend URI
-l, --lock <uri>	:memory:	Lock backend URI
-q, --queue <uri>	:memory:	Queue backend URI
-h, --host <host>	127.0.0.1	Host to bind to
-t, --tenant <tenant>	default	Tenant name
-v, --variable <name...>	—	Process only the specified named export(s). By default, all exports are processed.

What It Does

1. Starts an HTTP API and management server on http://localhost:3333
2. Compiles your source files with esbuild (watch mode)
3. Builds a manifesto in memory and uploads it to the local API
4. Re-uploads automatically when source files change

Backend URI Formats

Storage

Persists events and state snapshots.

URI	Description
:memory:	In-memory — data is lost on restart. Default for development.
postgres://user:pass@host:5432/dbname	PostgreSQL. Recommended for production.

Lock

Provides distributed mutual exclusion to prevent concurrent writes to the same stream partition.

URI	Description
:memory:	In-process mutex. Only safe for single-process deployments.
postgres://user:pass@host:5432/dbname	PostgreSQL advisory locks. Safe across multiple processes.

Queue

Delivers events from the event store to stream and aggregation workers.

URI	Description
:memory:	In-memory. Messages are lost on restart.
postgres://user:pass@host:5432/dbname	PostgreSQL-backed queue.
amqp://user:pass@host:5672/vhost	AMQP broker (e.g. RabbitMQ). Use amqps:// for TLS.
pubsub://project-id/topic-name	Google Cloud Pub/Sub. Enables horizontal scaling across multiple worker instances.

Examples

# Minimal — everything in-memory, great for local dev
iwentsourcing serve src/state/export.ts

# PostgreSQL storage and lock, in-memory queue
iwentsourcing serve src/state/export.ts \
  --storage postgres://user:pass@localhost:5432/mydb \
  --lock    postgres://user:pass@localhost:5432/mydb

# Full production-like setup
iwentsourcing serve src/state/export.ts \
  --storage postgres://user:pass@localhost:5432/mydb \
  --lock    postgres://user:pass@localhost:5432/mydb \
  --queue   pubsub://my-gcp-project/iwentsourcing \
  --tenant  acme

# Only process a subset of exports
iwentsourcing serve src/state/export.ts --variable todoStream personalTodoAggregation