create-mock-service

CLI to scaffold a fully-typed mock API service with Postman-style request matching, Zod validation, auto OpenAPI, and typed frontend client generation.

Quick Start

npx create-mock-service my-api
cd my-api
bun install
bun run dev

Open http://localhost:8787/docs — Swagger UI with interactive docs.

What You Get

my-api/
  mock.config.ts          ← Server config (base path, security, groups, OpenAPI metadata)
  routes.config.ts        ← Declarative endpoint manifest
  src/
    contracts.ts          ← Shared Zod schemas (ErrorRes, MessageRes)
    types.ts              ← TypeScript type definitions
    data/                 ← Handler files (one per method)
      hello/
        GET.ts
        POST.ts
        {name}/
          GET.ts
    lib/                  ← Core engine (router, matcher, store)
    scripts/              ← Build, scaffold, dump, client generation
    generated/            ← Auto-generated routes + OpenAPI spec + FE client
  .docs/                  ← Full documentation + tutorials

Features

| Feature | Description | |---|---| | File-based routing | src/data/users/GET.ts → GET /api/users | | Postman-style matching | Declare examples, server auto-picks the best match by body, headers, or query params | | Zod validation | Request body validation with auto-400, typed responses | | Auto OpenAPI 3.0.3 | Zod schemas → accurate OpenAPI spec (enum, format, required) | | Swagger UI | Interactive docs at /docs with try-it-out | | Typed client gen | bun run generate:client → fully typed fetch functions for your frontend | | Shared contracts | Define ErrorRes once, reuse across all handlers | | Scaffold + dump | Sync config ↔ filesystem, or regenerate config from files | | Security | Bearer, API Key, OAuth2 — per-route or global | | Hot reload | Dev server watches files and rebuilds OpenAPI |

Example Handler

// src/data/hello/POST.ts
import { z } from 'zod';
import { ErrorRes } from '../../contracts.js';
import type { MockExample } from '../../types.js';

const Req = z.object({
  name: z.string().min(1),
  message: z.string().min(1),
});

const HelloCreated = z.object({
  id: z.string(),
  message: z.string(),
});

export const schema = {
  request: Req,
  responses: {
    201: HelloCreated,
    400: ErrorRes,
  },
};

export const examples = [
  {
    name: 'Create success',
    match: {
      body: Req.parse({ name: 'Alice', message: 'Hello' }),
    },
    response: {
      status: 201,
      body: HelloCreated.parse({ id: 'abc', message: 'Hello' }),
    },
  },
  {
    name: 'Missing name',
    match: {
      body: { message: 'Hello' },
    },
    response: {
      status: 400,
      body: ErrorRes.parse({ error: 'Name is required' }),
    },
  },
] satisfies MockExample[];

export default {
  status: 201,
  body: { id: 'abc', message: 'Hello created!' },
};

How matching works

POST /api/hello  { name: "Alice", message: "Hello" }
  → auto-matches "Create success" example → returns 201

POST /api/hello  { message: "Hello" }
  → auto-matches "Missing name" example → returns 400

POST /api/hello  {}
  → no example matches → returns the default export

Control matching explicitly with headers:

curl -H "X-Mock-Response-Name: Missing name" \
     -d '{"message":"Hello"}' \
     http://localhost:8787/api/hello

See .docs/tutorial/05-matching.md for the full matching algorithm.

Matching & Override Headers

| Header | Purpose | |---|---| | X-Mock-Response-Name | Select example by name | | X-Mock-Response-Code | Filter examples by status code | | X-Mock-Match-Request-Body | Require exact body match (true) | | X-Mock-Match-Request-Headers | Comma-separated header keys to match | | X-Mock-Scenario | Legacy scenario selection | | X-Mock-Delay | Artificial response delay (ms) |

Project Scripts

| Command | Description | |---|---| | bun run dev | Dev server + hot reload + auto OpenAPI rebuild | | bun run build | Build routes + lint | | bun run build:routes | Regenerate route manifest & OpenAPI spec | | bun run scaffold | Sync routes.config.ts → filesystem | | bun run dump:routes | Scan files → update routes.config.ts | | bun run create:endpoint | Interactive new handler generator | | bun run generate:client | Generate typed FE client from Zod schemas | | bun run lint | TypeScript type check |

Requirements

• Node.js 18+
• Bun (recommended) or npm

Documentation

After generating a project, see:

• .docs/tutorial/ — Step-by-step hands-on guides (English)
• README.md (in generated project) — Project overview

License

MIT