api-emulator is a local app store for stateful API clones. Run GitHub, Stripe, Resend, and plugin powered providers on localhost, seed state, inspect behavior, reset data, and test your app in one place.

Why use it?

• Test API integrations locally without real provider credentials.
• Run multiple provider clones together, with shared state, auth, webhooks, seed data, and resets.
• Keep provider behavior in plugins so public, private, and internal APIs can live outside your app.

Quick start

npx -p api-emulator api
npx -p api-emulator api --service github,stripe,resend
npx -p api-emulator api --no-notify

Then point your app at the local provider URLs:

http://localhost:4000/github
http://localhost:4000/stripe
http://localhost:4000/resend

Use trusted local HTTPS names when your app needs browser compatible origins:

npx -p api-emulator api --service github,stripe,resend --portless

https://github.api-emulator.localhost
https://stripe.api-emulator.localhost
https://resend.api-emulator.localhost

Create starter config and list available services:

npx -p api-emulator api init
npx -p api-emulator api list

Agent instructions

For coding agents, use the short agent-facing reference at https://api-emulator.jsj.sh/agent.txt. Copy this into your agent prompt:

Read https://api-emulator.jsj.sh/agent.txt before using api-emulator.

Use in tests

import { createEmulator } from "api-emulator";

const github = await createEmulator({ service: "github", port: 4001 });
process.env.GITHUB_API_BASE = github.url;

afterEach(() => github.reset());
afterAll(() => github.close());

Capture and replay a stable fixture after a stochastic or stateful run:

const fixture = github.exportFixture({ metadata: { name: "pull-request-flow" } });

github.resetToFixture(fixture);

Plugins

Install more providers from a public or internal plugin shelf:

npx -p api-emulator api install posthog
npx -p api-emulator api install pepper --no-package-manager

Or load a plugin file directly:

npx -p api-emulator api --plugin ./api-emulator-plugins/@posthog/api-emulator.mjs --service posthog

The installer auto discovers sibling api-emulator-plugins and api-emulator-internal checkouts. Set API_EMULATOR_PLUGIN_CATALOGS=/path/to/shelf,/path/to/internal to add more shelves.

Sanity check a plugin before installing or loading it:

npx -p api-emulator api validate-plugin posthog
npx -p api-emulator api validate-plugin ./api-emulator-plugins/@posthog/api-emulator.mjs

Scaffold a local provider clone and catalog entry:

npx -p api-emulator api clone create internal-billing

The scaffold includes starter fidelity metadata so api list can show whether a provider is still a stub, partially covered, or contract-backed. api plugin create remains available as a compatibility alias. Generated scaffolds and agent skills are tracked in .api-emulator/manifest.json so reruns avoid overwriting local edits unless you pass --yes.

Install local agent skills for plugin authoring and runtime workflows:

npx -p api-emulator api init --skills-only --agents agents

Use --agents user-agents to install into ~/.agents/skills.

On macOS, api-emulator shows a best effort notification when the server is ready. Use --no-notify to silence it. Add --notify to get completion notifications for init, install, validate-plugin, and plugin scaffold commands.

A plugin exports a ServicePlugin:

import type { ServicePlugin } from "@api-emulator/core";

export const plugin: ServicePlugin = {
  name: "internal-billing",
  register(app) {
    app.get("/v1/customers", (c) => c.json({ data: [] }));
  },
};

Next.js embedded mode

npm install @api-emulator/adapter-next @api-emulator/core

import { createApiEmulatorHandler } from "@api-emulator/adapter-next";
import type { ServicePlugin } from "@api-emulator/core";

const internalPlugin: ServicePlugin = {
  name: "internal",
  register(app) {
    app.get("/health", (c) => c.json({ ok: true }));
  },
};

export const { GET, POST, PUT, PATCH, DELETE } = createApiEmulatorHandler({
  services: {
    internal: { emulator: { plugin: internalPlugin } },
  },
});

Configuration

npx -p api-emulator api init creates api-emulator.config.yaml.

tokens:
  test_token_admin:
    login: admin
    scopes: [repo, user]

github:
  users:
    - login: octocat
      name: The Octocat

The CLI auto-detects api-emulator.config.yaml, .yml, and .json.

Examples

• examples/oauth
• examples/nextjs-embedded
• examples/resend-magic-link
• examples/stripe-checkout

Development

bun install
bun run build
bun run format:check
bun run type-check
bun run lint
bun run test

Links

• jsj/api-emulator-plugins
• api-emulator on npm

License

MIT