page.mdx

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)
tls	none	Serve over HTTPS. Object of the form {`{ cert, key }`} where each value is a PEM string or Buffer. When set, url uses the https:// scheme.

HTTPS

Pass a tls option with PEM-encoded cert and key material to serve the emulator over HTTPS. Material is accepted in-memory — load it from disk, generate it on the fly, or source it from a secret store.

import { readFileSync } from 'node:fs'
import { createEmulator } from 'emulate'

const github = await createEmulator({
  service: 'github',
  port: 4001,
  tls: {
    cert: readFileSync('./certs/localhost.crt'),
    key: readFileSync('./certs/localhost.key'),
  },
})

github.url // 'https://localhost:4001'

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.