Skip to content

page.mdx

Latest commit

 

History

History
270 lines (236 loc) · 8.02 KB

page.mdx

File metadata and controls

270 lines (236 loc) · 8.02 KB
Raw

Getting Started

Local drop-in replacement for Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Okta, MongoDB Atlas, Resend, and Stripe APIs. Built for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation. Not mocks.

Quick Start

npx emulate

All services start with sensible defaults. No config file needed:

  • Vercel on http://localhost:4000
  • GitHub on http://localhost:4001
  • Google on http://localhost:4002
  • Slack on http://localhost:4003
  • Apple on http://localhost:4004
  • Microsoft on http://localhost:4005
  • Okta on http://localhost:4006
  • AWS on http://localhost:4007
  • Resend on http://localhost:4008
  • Stripe on http://localhost:4009
  • MongoDB Atlas on http://localhost:4010
  • Clerk on http://localhost:4011
  • Spotify on http://localhost:4012
  • PostHog on http://localhost:4016

Control Plane

Every service exposes a public control plane under /_emulate.

Route Purpose
GET /_emulate Human-readable landing page for the service instance
GET /_emulate/manifest Machine-readable service manifest with supported surfaces, auth capabilities, and spec coverage
GET /_emulate/quickstart Plain-text instructions for humans and agents
GET /_emulate/specs Advertised specs and protocol surfaces
GET /_emulate/coverage Per-operation spec coverage with a summary by status (generated, hand-authored, partial, unsupported)
GET /_emulate/connections Copyable SDK, CLI, env, and curl snippets resolved against this instance (optional ?token=,{" "} ?client_id=, ?client_secret=)
GET /_emulate/openapi Redirect to the advertised OpenAPI document when one exists
GET /_emulate/graphql Return the GraphQL endpoint when the service exposes one
GET /_emulate/mcp Return the MCP endpoint when the service exposes one
GET /_emulate/state Current emulator store snapshot
GET /_emulate/ledger Recent API calls with sensitive fields redacted. See Request Ledger
DELETE /_emulate/ledger Clear the request ledger
POST /_emulate/faults Arm a one-shot or counted fault against matching provider requests
GET /_emulate/faults List armed faults with remaining counts
DELETE /_emulate/faults Clear all armed faults
DELETE /_emulate/faults/:id Clear one armed fault
GET /_emulate/logs Webhook deliveries plus the most recent provider requests
POST /_emulate/reset Reset state, webhooks, and the request ledger, then replay seed data
POST /_emulate/seed Add runtime seed data using the service seed schema
POST /_emulate/credentials Create bearer tokens, API keys, OAuth clients, or client-credentials apps where supported
POST /_emulate/instances Return URLs for a lazily created hosted instance

The manifest advertises only the surfaces that match the real service. Specs such as OpenAPI, GraphQL, MCP, OAuth metadata, and Google discovery documents can inform an emulator, but they are not treated as proof that every protocol exists for every service. The Service Manifest is the single source of truth for what each emulator supports.

Service host

A bare service host such as https://github.emulators.dev (no instance) serves a service-level control plane so it is useful before you create an instance: GET /_emulate, /_emulate/manifest, /_emulate/quickstart, /_emulate/specs, /_emulate/coverage, /_emulate/connections, /_emulate/openapi, and POST /_emulate/instances.

Service catalog

GET /_emulate/services returns a machine-readable catalog of every hosted service, including its id, name, description, service host, instance host pattern, path form, and manifest URL. It is available from any host so consoles and agents can discover what is deployed. See Deployment.

Credential creation follows each service's real shape. GitHub can mint bearer tokens for users, Spotify creates client credentials apps, OAuth/OIDC providers create clients, Stripe and Resend create API-key style credentials, and AWS advertises provider-specific SDK credentials.

Deployed Instances

Hosted services are available on host-based routing. Cloudflare deployments support service hosts, instance hosts, and a compatibility path form:

https://github.emulators.dev               # service host
https://github.my-instance.emulators.dev   # instance host
https://emulators.dev/github/my-instance    # path form

The instance host and path form route to the same stateful service instance. The instance host form is preferred for public examples because the provider base URL is the origin itself, which better matches service-owned hosts. The control plane for the instance host form lives at https://github.my-instance.emulators.dev/_emulate.

See Deployment for the host-based routing model, the emulate-hosts Cloudflare worker, and the Durable Object instance model.

CLI

# Start all services (zero-config)
npx emulate

# Start specific services
npx emulate --service vercel,github

# Custom port
npx emulate --port 3000

# Use a seed config file
npx emulate --seed config.yaml

# Generate a starter config
npx emulate init

# Generate config for a specific service
npx emulate init --service github

# List available services
npx emulate list

Options

Flag Default Description
-p, --port 4000 Base port (auto-increments per service)
-s, --service all Comma-separated services to enable
--seed auto-detect Path to seed config (YAML or JSON)

The port can also be set via EMULATE_PORT or PORT environment variables.

Programmatic API

You can also use emulate as a library in your tests. See the Programmatic API page for createEmulator, Vitest/Jest setup, and instance methods.

Next.js Integration

Embed emulators directly in your Next.js app so they run on the same origin. See the Next.js Integration page for setup instructions.