Custom emulators

Bring a third-party provider's HTTP API into local development, tests, and agent sandboxes. Implement the provider behavior your integration uses, run it alongside built-in services, and share the definition as a package.

Use the project's existing package manager for changes. End-user CLI examples use npx emulate because bare emulate is a zsh built-in. Requires Node 24 or later.

Local listeners bind to 127.0.0.1 by default. For access from containers or other machines, pass --host 0.0.0.0 to the CLI or hostname: '0.0.0.0' to createEmulator. Configure --base-url or baseUrl for advertised URLs reachable by those clients.

Start from the scaffold when creating an emulator:

npm install -D emulate
npx emulate init --custom inventory
npx emulate start --watch

The scaffold creates a TypeScript definition and a Node test for an inventory API. Adapt its routes, state, and test to the third-party provider. It adds an entry to a discovered YAML, JSON, TypeScript, or JavaScript config, preserving existing services. For an unusual executable config, follow the manual import and registration instructions printed by the command. init prints the generated test path; use the service URL and Inspector link printed by start for requests because the port depends on the config.

Define the service with defineEmulator imported from emulate. state() returns fresh JSON-compatible data, and synchronous setup({ app, state, baseUrl, signal, onDispose }) registers handlers. State is inferred. Implement observable state transitions, validation, and errors from the actual API contract. Use author-controlled response shapes and IDs.