custom-apis

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.

Keep mutable state in state(), not module-level variables. seed fully replaces initial state. Add validateSeed(value) for external fixtures. Snapshots are detached and versioned; increment stateVersion when changing persisted shape. Reset restores the captured seed and recreates handlers. Restore changes current state without changing the reset baseline.

The router provides get, post, put, patch, delete, on, use, onError, and notFound. Use c.req for headers, parameters, query, JSON, text, forms, or bytes, and return a native Response or c.json/text/html/body/redirect. Append cookies with c.header('Set-Cookie', value, { append: true }) to retain cookies already on the response. It is not a complete Hono implementation. There is no implicit custom authentication or rate limit. Keep /_emulate reserved for management.

Use baseUrl for advertised URLs, the lifecycle signal for asynchronous work, and onDispose for cleanup. An await can interleave concurrent handlers; protect domain invariants accordingly.

Register definitions in defineConfig({ services: { inventory: { emulator: inventory } } }). YAML/JSON entries can use local module paths or installed packages. Paths resolve from the config project. The CLI uses Node built-ins with support for TypeScript path aliases and inherited JSONC tsconfig files. Node 26 accepts erasable TypeScript only; compile enums and parameter properties to JavaScript before loading them. Node 24 also supports native TypeScript transforms. Use erasable TypeScript for definitions shared with native Node tests; JSX and compiler plugins are unsupported. Built-ins can appear alongside custom services. Instance names must not replace built-in names.

Validate the API in process:

const api = await createEmulator({ service: inventory, listen: false })
try {
  await api.request('/reservations', { method: 'POST' })
  const state = await (await api.request('/inventory')).json()
  await api.reset()
} finally {
  await api.close()
}

Import createEmulator from emulate. Use port: 0 and the returned url for HTTP SDK tests. Run the scaffold's test with node --test emulators/inventory.test.ts. Test reads after writes, domain errors, reset, and independent instances. Do not describe an API as implemented based only on matching response schemas.