Programmatic API

Use emulators as libraries in your tests and scripts. There are two approaches: the @deploybaseline/cli package (which wraps all services) and the individual @deploybaseline/* scoped packages.

CLI package

The @deploybaseline/cli package provides a createEmulator helper that starts any service by name.

npm install @deploybaseline/cli

import { createEmulator } from "@deploybaseline/cli";

const github = await createEmulator({ service: "github", port: 4001 });
const stripe = await createEmulator({ service: "stripe", port: 4002 });

github.url; // 'http://localhost:4001'
stripe.url; // 'http://localhost:4002'

await github.close();
await stripe.close();

Each built-in emulator runs in its own Node process, as it does under the CLI, so starting one takes around 100 ms. Start one per test suite and call reset() between tests, as below, rather than one per test. close() stops the process. Custom emulators run in your test process.

Generated secrets

When a GitHub App omits private_key, createEmulator generates an RSA-2048 PKCS#1 key for that emulator instance:

const github = await createEmulator({
  service: "github",
  seed: {
    github: {
      users: [{ login: "octocat" }],
      apps: [
        {
          app_id: 12345,
          slug: "my-github-app",
          name: "My GitHub App",
          installations: [{ installation_id: 100, account: "octocat" }],
        },
      ],
    },
  },
});

const privateKey = github.generatedSecrets.find(
  (secret) => secret.kind === "github.app_private_key" && secret.id === "12345",
)?.value;

Generated keys remain stable across reset() calls and appear only in generatedSecrets. Explicitly configured keys are never returned there. A new createEmulator call generates a new key.

Vitest / Jest setup

// vitest.setup.ts
import { createEmulator, type Emulator } from "@deploybaseline/cli";

let github: Emulator;
let stripe: Emulator;

beforeAll(async () => {
  [github, stripe] = await Promise.all([
    createEmulator({ service: "github", port: 4001 }),
    createEmulator({ service: "stripe", port: 4002 }),
  ]);
  process.env.GITHUB_EMULATOR_URL = github.url;
  process.env.STRIPE_EMULATOR_URL = stripe.url;
});

afterEach(() => Promise.all([github.reset(), stripe.reset()]));
afterAll(() => Promise.all([github.close(), stripe.close()]));

createEmulator options

Option	Default	Description
`service`		Service name: `‘github’`, `‘google’`, `‘slack’`, `‘apple’`, `‘microsoft’`, `‘okta’`, `‘resend’`, `‘stripe’`, `‘clerk’`, `‘linear’`, or `‘twilio’`
`port`	`4000`	Port for the HTTP server
`hostname`	`127.0.0.1`	Listening address for built-in and custom emulators
`seed`	none	Inline seed data (same shape as a provider’s section in the config file)
`baseUrl`	none	Override the advertised base URL (used in OAuth redirects, webhook URLs, etc.). Per-service `baseUrl` in seed config takes highest priority, then this option, then the `BASELINE_BASE_URL` env var (supports template), then .
`state`	none	Keep state across restarts: a JSON file path, `sqlite:<path>`, or `libsql://` URL (locked to one emulator at a time), or a `PersistenceAdapter` such as `sqliteState()`. Saved state wins over `seed`. See Saved state.
`resetState`	`false`	Ignore saved state, reseed, and overwrite it
`saveDebounceMs`	`250`	Wait after a change before saving; `close()` always saves
`version`	this CLI’s range	Provider version range for a built-in service, such as `‘^0.14’`. The provider comes from the project’s `node_modules`, the provider cache, or a pull from npm. See Provider versions
`offline`	`false` (or `BASELINE_OFFLINE=1`)	Never touch the network when finding the provider
`faults`	none	Injected latency and errors, in the same shape as a service’s `faults` config. Also read from the service’s seed section. Off unless set. See Fault injection

Use hostname: '0.0.0.0' to allow connections from containers or other machines, and baseUrl to advertise a URL reachable by those clients. This option also applies to custom definitions passed to createEmulator.

Instance methods

Method	Description
`url`	Base URL of the running server
`generatedSecrets`	Readonly secrets generated while preparing seed data (reused from saved state when restored)
`restored`	`true` when the emulator started from saved state instead of seeding
`reset()`	Wipe the store and replay seed data (saved too, with `state`). Returns a Promise: await it before the next request
`flush()`	Write pending state now (with `state`)
`snapshot()`	Resolves to the current state as a state file object
`restore(state)`	Replace the current state with a `snapshot()` result, or a state file’s contents (object or JSON text). Resolves to
`saveSnapshot(name)`	Save the current state under a name: a file next to `state`, otherwise in memory
`restoreSnapshot(name)`	Replace the current state with a named snapshot
`listSnapshots()`, `deleteSnapshot(name)`	List or delete named snapshots
`close()`	Shut down the HTTP server, close WebSocket connections (code 1001), and save state; returns a Promise

Scoped packages

Each emulator is published as its own @deploybaseline/* package. Install only the ones you need:

npm install @deploybaseline/github @deploybaseline/google @deploybaseline/linear @deploybaseline/twilio

Available packages

One package per provider, in the same categories as the Providers page, plus the kits they share:

Package	Provider	What is emulated
Identity and auth
`@deploybaseline/auth0`	Auth0	Universal Login, OAuth and OIDC, Management API, role-based access control
`@deploybaseline/clerk`	Clerk	Frontend API, Backend API, OAuth and OIDC, organizations, sessions, JWT templates
`@deploybaseline/okta`	Okta	OAuth 2.0 and OIDC, authorization servers, users, groups, apps
`@deploybaseline/apple`	Apple	Sign in with Apple: authorization, client secrets, ID tokens, server-to-server notifications
Workspace and productivity
`@deploybaseline/google`	Google	OAuth 2.0 and OIDC, Gmail, Calendar, Drive, Sheets, Docs
`@deploybaseline/microsoft`	Microsoft	Entra ID OAuth 2.0 and OIDC, Microsoft Graph: Outlook mail, calendar, contacts, To Do, users and groups; SharePoint Online and OneDrive over Graph and the SharePoint REST API
`@deploybaseline/notion`	Notion	Pages, databases and data sources, queries, search, blocks, comments, OAuth, webhooks
Messaging and email
`@deploybaseline/slack`	Slack	Web API, OAuth v2, incoming webhooks, interactivity, events, Socket Mode
`@deploybaseline/discord`	Discord	Bot REST API, Gateway over WebSocket, interactions, OAuth2, rate limits
`@deploybaseline/twilio`	Twilio	Programmable Messaging, Messaging Services, Verify, Voice, Conversations
`@deploybaseline/whatsapp`	WhatsApp	Cloud API messages, templates, media, phone numbers and accounts, webhooks
`@deploybaseline/resend`	Resend	Emails, idempotency, domains, API keys, audiences and contacts, a local inbox
`@deploybaseline/sendgrid`	SendGrid	Mail Send, scheduling, templates, API keys, Marketing, Event Webhook, a local inbox
Payments and commerce
`@deploybaseline/stripe`	Stripe	Customers, Payment and Setup Intents, charges, refunds, subscriptions, invoices, Checkout, Connect, webhooks
`@deploybaseline/paypal`	PayPal	Orders v2, a hosted approval page, Payments v2, webhooks
`@deploybaseline/square`	Square	Payments, refunds, orders, customers, catalog, locations, OAuth, webhooks
`@deploybaseline/plaid`	Plaid	Link, items and accounts, transactions, institutions, sandbox helpers, webhooks
`@deploybaseline/shopify`	Shopify	Admin GraphQL API, OAuth, webhooks
Developer platforms
`@deploybaseline/github`	GitHub	REST and GraphQL: repositories, issues, pull requests, organizations, webhooks, Actions, Checks, OAuth Apps and GitHub Apps
`@deploybaseline/linear`	Linear	GraphQL API, OAuth, webhooks
`@deploybaseline/jira`	Jira	REST API, JQL search, Agile boards and sprints, OAuth 2.0 (3LO), webhooks
CRM and support
`@deploybaseline/salesforce`	Salesforce	Records, SOQL, describe, sObject collections, composite requests, OAuth
`@deploybaseline/hubspot`	HubSpot	CRM objects, search, associations, properties, pipelines, owners, OAuth, webhooks
`@deploybaseline/zendesk`	Zendesk	Tickets, comments, users, organizations and groups, search, views, triggers, OAuth, webhooks
`@deploybaseline/servicenow`	ServiceNow	Table API, Attachment API, Aggregate API
Finance and ERP
`@deploybaseline/netsuite`	NetSuite	Records, transforms, SuiteQL, custom fields and records, metadata, OAuth 2.0
`@deploybaseline/quickbooks`	QuickBooks	Accounting entities, queries, batch, change data capture, OAuth 2.0, webhooks
`@deploybaseline/xero`	Xero	Accounting API, OAuth 2.0 and OpenID Connect, webhooks
Shared
`@deploybaseline/core`	Shared store, middleware, and utilities
`@deploybaseline/graphql`	GraphQL kit (Linear, GitHub, and Shopify run on it)
`@deploybaseline/ws`	WebSocket kit (Slack Socket Mode and the Discord Gateway run on it, and bundle it)

Direct usage

Each scoped package exports its service plugin and seed helpers:

import * as github from "@deploybaseline/github";
import * as stripe from "@deploybaseline/stripe";

These are the same modules the CLI loads internally.

Custom emulators

Custom definitions created with defineEmulator from @deploybaseline/cli work in the CLI and in in-process tests. The same definition provides typed state, HTTP handlers, reset, versioned snapshots, and optional inspection/persistence. See Custom emulators for the quickstart, API reference, and complete lifecycle semantics.

Getting started

Configuration

Custom emulators

Reference

CLI package

Generated secrets

Vitest / Jest setup

createEmulator options

Instance methods

Scoped packages

Available packages

Direct usage

Custom emulators

​CLI package

​Generated secrets

​Vitest / Jest setup

​createEmulator options

​Instance methods

​Scoped packages

​Available packages

​Direct usage

​Custom emulators

CLI package

Generated secrets

Vitest / Jest setup

createEmulator options

Instance methods

Scoped packages

Available packages

Direct usage

Custom emulators