Programmatic API

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

CLI package

The emulate package provides a createEmulator helper that starts any service by name.

npm install emulate

import { createEmulator } from 'emulate'

const github = await createEmulator({ service: 'github', port: 4001 })
const vercel = await createEmulator({ service: 'vercel', port: 4002 })

github.url   // 'http://localhost:4001'
vercel.url   // 'http://localhost:4002'

await github.close()
await vercel.close()

Vitest / Jest setup

// vitest.setup.ts
import { createEmulator, type Emulator } from 'emulate'

let github: Emulator
let vercel: Emulator

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

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

createEmulator options

Option	Default	Description
`service`	(required)	Service name: `'vercel'`, `'github'`, `'google'`, `'slack'`, `'apple'`, `'microsoft'`, `'aws'`, `'okta'`, `'mongoatlas'`, `'resend'`, or `'stripe'`
`port`	`4000`	Port for the HTTP server
`seed`	none	Inline seed data (same shape as YAML config)
`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 `EMULATE_BASE_URL` env var (supports `{service}` template), then `PORTLESS_URL` (supports `{service}`, automatically set by the `portless` CLI wrapper), then `http://localhost:<port>`.

Instance methods

Method	Description
`url`	Base URL of the running server
`reset()`	Wipe the store and replay seed data
`close()`	Shut down the HTTP server, returns a Promise

Scoped packages

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

npm install @emulators/github @emulators/google @emulators/stripe

Available packages

Package	Service
`@emulators/vercel`	Vercel API
`@emulators/github`	GitHub API
`@emulators/google`	Google OAuth, Gmail, Calendar, Drive
`@emulators/slack`	Slack Web API, OAuth v2, webhooks
`@emulators/apple`	Apple Sign In / OIDC
`@emulators/microsoft`	Microsoft Entra ID, Graph API
`@emulators/aws`	AWS S3, SQS, IAM, STS
`@emulators/okta`	Okta identity provider / OIDC
`@emulators/mongoatlas`	MongoDB Atlas Admin API + Data API
`@emulators/resend`	Resend email API
`@emulators/stripe`	Stripe billing and payments API
`@emulators/core`	Shared store, middleware, and utilities
`@emulators/adapter-next`	Next.js App Router integration

Direct usage

Each scoped package exports its Hono app and seed function, so you can compose emulators however you like:

import * as github from '@emulators/github'
import * as stripe from '@emulators/stripe'

These are the same modules used internally by the CLI and the Next.js adapter. See the Next.js Integration page for a full example of using scoped packages with createEmulateHandler.