specshot

SpecShot

One command. Zero dependencies. 100% type-safe API client.

Drop an OpenAPI spec in, get production-ready TypeScript out. No SDKs to install. No generated bloat to maintain. You own every line — like shadcn/ui, but for your API layer.

Why SpecShot?

Instead of...	You get...
Vendor lock-in SDKs	Code you own, edit, and extend
Black-box generators	100% customizable Handlebars templates
Hardcoded architecture	Bring your own patterns (Classes, Hooks, Functions)
Untyped fetch()	Strictly typed endpoints and models

What you get

• Template-Driven Engine — SpecShot doesn't dictate your architecture. It ships with robust built-in presets (class, functional), but you can easily eject and modify the Handlebars templates to match your exact team standards.
• Custom Code Preservation — Write your own custom methods directly inside the generated files using magic comments (// --- CUSTOM CODE START ---). Your code survives the next generation.
• 100% Code Ownership — Generate it once, own it forever. No proprietary libraries or hidden runtime dependencies injected into your project unless your chosen template requires them.
• Built-in Mock Server — Instantly spin up a local Mock API dashboard that serves realistic data generated from your OpenAPI spec.

30 Seconds

# 1. Scaffold the core
npx specshot init

# 2. Point at your spec
npx specshot generate --url http://localhost:8080/openapi.json

# 3. Use it

import { clientApi, defaultClient } from "./lib/api/default";

// Override the base URL if needed
defaultClient.options.baseUrl = "https://api.myprod.com";

// Everything is typed — no generics, no casting
const { data, error, ok } = await clientApi.pets.listPets();
const { data: pet } = await clientApi.pets.getPet("abc123");
const result = await clientApi.pets.createPet({
  name: "Buddy",
  species: "dog",
});

That's it. No config files. No code generation pipelines. Just typed API calls.

Commands

1. init (One-time setup)

Creates a specshot.config.mjs configuration file with your preferences. No files are installed — generate handles all installation.

Interactive mode:

npx specshot init

Non-interactive mode (CI/CD friendly):

npx specshot init \
  --preset class \
  --url http://localhost:8080/openapi.json

Flag	Description
--preset <name>	Preset: class, functional, or community/custom
--templates, -t <dir>	Custom Handlebars templates directory
--url, -u <url>	OpenAPI JSON URL to save in config for later generation

2. generate (Run repeatedly on API updates)

Installs the API core infrastructure (if missing), then reads your OpenAPI spec to generate strictly-typed API services, Zod schemas, and models.

Presets

Choose a built-in code style with --preset:

Preset	Style	Dependencies	Result pattern
class (default)	BaseService + ApiClient + Zod	zod	Promise<{ data, error, ok }>
functional	Standalone async function + native fetch()	none	Promise<T> (throws on error)

npx specshot generate --preset functional

Or set it in config:

export default {
  preset: "functional",
  apis: { ... }
};

If you already provided a --url during init (which saves it to specshot.config.mjs), you can simply run:

npx specshot generate

(No flags or prompts required! Perfect for an npm run api:sync script.)

Or, if you want to override the source:

npx specshot generate --url http://localhost:8080/openapi.json

Auto-install: When using built-in templates, generate automatically installs the API Core (ApiClient, BaseService, types) and Provider skeleton (client.ts, plugins, hooks) if they don't already exist. When using custom templates, infrastructure installation is skipped.

generate options

Flag	Description
--url, -u <url>	Remote OpenAPI spec URL
--file, -f <path>	Local OpenAPI JSON file
--output, -o <dir>	Output directory
--alias, -a <alias>	Import alias (e.g. @/lib/api)
--config, -c <path>	Custom config file path
--templates, -t <dir>	Custom Handlebars templates (partial override)
--preset <name>	Built-in preset: class, functional
-w, --watch	Watch for changes and auto-regenerate
--dry-run	Preview without writing files
--msw	Generate MSW mock handlers
--force-scaffold	Force regenerate scaffold files, overwriting existing ones

3. templates (Manage Handlebars templates)

Subcommands for template management:

templates eject

Copies a built-in or community preset to your project as a custom preset so you can customize it. Only the templates you edit will override the built-ins — missing files automatically fall back to defaults.

npx specshot templates eject class
npx specshot templates eject functional --output ./my-templates

Flag	Description
--output, -o <dir>	Output directory (default: .specshot/templates/presets/)
--generator-only	Eject only generator templates
--msw-only	Eject only MSW templates

templates list

Shows all available templates and their current override status (built-in / dir override / per-file override).

npx specshot templates list

templates context <name>

Shows all available variables and naming helpers for a specific template.

npx specshot templates context service
npx specshot templates context models

templates install <package>

Install a community preset from npm or GitHub:

npx specshot templates install github:user/my-preset

templates uninstall <preset>

Remove an installed community preset:

npx specshot templates uninstall my-preset

templates validate

Validate preset structure and _preset.json for community templates:

npx specshot templates validate

Then generate with your custom templates:

npx specshot generate --templates ./my-templates

Template structure

my-templates/
  models.hbs              # Generator: shared Zod schemas + types
  types.hbs               # Generator: per-tag request/response types
  service.hbs             # Generator: per-tag service class
  index.hbs               # Generator: provider index + clientApi export
  plugins-index.hbs       # Generator: plugin auto-wiring
  msw/
    handlers.hbs          # MSW: per-tag http.<method>() handlers
    index.hbs             # MSW: handler barrel export
    browser.hbs           # MSW: setupWorker entry

Partial override

You don't need to copy all templates. Place only the files you want to customize in your override directory. Any missing file will use the built-in default automatically.

For example, to customize only the service template:

my-templates/
  service.hbs    # Your custom version

npx specshot generate --templates ./my-templates
# models.hbs, types.hbs, index.hbs → built-in defaults
# service.hbs → your custom version

Template context

Templates use standard Handlebars syntax. Key variables available:

Template	Context variables
models.hbs	schemas (shared), version, customCode
types.hbs	tag, imports, specificSchemas, operations, customCode
service.hbs	className, tagPrefix, exportsToReExport, operations, corePath, customCode
index.hbs	services, corePath, pluginsPath, customCode
handlers.hbs	tag, tagLowerCase, handlers, typeImports, usesFaker, typesImportPath

Each generated file preserves a // --- CUSTOM CODE START --- / // --- CUSTOM CODE END --- block so your hand-written code survives regeneration.

Handlebars naming helpers

Custom templates can use built-in naming helpers:

Helper	Example input	Output
capitalize	pets	Pets
camelCase	pet-store	petStore
pascalCase	pet-store	PetStore
kebabCase	PetStore	pet-store
snakeCase	PetStore	pet_store
toLowerCase	PetStore	petstore
toUpperCase	petstore	PETSTORE
ifEq	{{#ifEq tag "pets"}}...{{/ifEq}}	Conditional block
ifNeq	{{#ifNeq tag "users"}}...{{/ifNeq}}	Negated conditional

File naming configuration

Control generated file names via fileNaming in config:

export default {
  apis: {
    petstore: {
      openapiUrl: "./openapi.json",
      fileNaming: {
        models: "schemas", // → schemas.ts
        service: "{{pascalCase tag}}Service", // → PetsService.ts
        types: "{{pascalCase tag}}Types", // → PetsTypes.ts
        index: "index", // → index.ts
      },
    },
  },
};

Custom output paths

Control WHERE generated files go via outputPaths in config:

export default {
  apis: {
    default: {
      openapiUrl: "./openapi.json",
      outputPaths: {
        models: "src/models",
        services: "src/services",
        types: "src/types",
        index: "src/api",
      },
    },
  },
};

Import paths between files are computed automatically. See docs/template-variables.md for full reference.

Editor autocompletion

SpecShot provides autocompletion for both config files and templates:

Config files (specshot.config.mjs):

/**
 * @typedef {Object} TemplateData
 * @property {"react-query" | "swr" | "none"} [hook] - Hooks framework
 * @property {("bearer" | "logger" | "request-id" | "circuit-breaker")[]} [pluginNames] - Plugins to generate
 * @property {"types-only" | "zod-schemas" | "zod-runtime"} [validation] - Validation strictness mode
 */
/** @type {import('specshot').SpecshotConfig<TemplateData>} */
export default {
  // Autocompletion works in VS Code with the TypeScript language server
  preset: "functional",
  apis: {/* ... */},
  templateData: {
    hook: "none",
    pluginNames: [],
    validation: "zod-runtime",
  },
};

For JSON config files (specshot.config.json), add a $schema reference:

{
  "$schema": "https://specshot.dev/config.schema.json",
  "preset": "functional"
}

Template files (.hbs):

• Run specshot templates context <name> to see available variables in the CLI
• See docs/template-variables.md for the full reference

mock (Zero-config API Mocking)

SpecShot includes a powerful built-in mock server and Web Dashboard. No MSW or complex setup required.

npx specshot mock --web --proxy http://localhost:3000

Flag	Description
--web	Launch the interactive Web Dashboard (SPA)
--proxy, -p <url>	Proxy un-mocked requests to a real backend
--port <number>	Port for the mock API server (default: 3457)
--no-open	Prevent opening the browser automatically

🎛️ Mock Dashboard Features

When you run with --web, SpecShot opens a beautiful dashboard where you can:

• Toggle Endpoints: Turn mock responses on/off per endpoint.
• Set Latency & Errors: Simulate slow networks or 500/400 error states instantly.
• Customize Data (Faker.js): Use the searchable dropdown to map specific JSON fields to Faker.js functions (e.g., internet.email, image.url).
• Manual Overrides: Write custom JSON payloads directly in the browser.
• WebSocket Mocking: Configure WebSocket endpoints and push events to connected clients in real-time from the dashboard.

(Mock configurations and overrides are automatically saved to .specshot/mocks.json so your team can share the same mock state!)

specshot.config.mjs

/**
 * @typedef {Object} TemplateData
 * @property {"react-query" | "swr" | "none"} [hook] - Hooks framework
 * @property {("bearer" | "logger" | "request-id" | "circuit-breaker")[]} [pluginNames] - Plugins to generate
 * @property {"types-only" | "zod-schemas" | "zod-runtime"} [validation] - Validation strictness mode
 */
/**
 * @typedef {Object} Overrides
 * @property {string} [dir]
 * @property {string} [browser]
 * @property {string} [core]
 * @property {string} [handlerPerTag]
 * @property {string} [index]
 * @property {string} [plugins]
 * @property {string} [provider]
 * @property {string} [servicePerTag]
 * @property {string} [typesPerTag]
 */
/** @type {import('specshot').SpecshotConfig<TemplateData, Overrides>} */
export default {
  preset: "class", // class or functional
  templates: "src/lib/api/templates", // string (dir) or object (per-file)

  // Custom Faker.js plugins for mock generation
  fakerPlugins: [
    {
      name: "custom-image",
      match: (ctx) => ctx.path.endsWith("imageUrl"),
      generate: (faker) => faker.image.url(),
    },
  ],

  // Template data passed to all templates
  templateData: {
    hook: "swr", // swr, react-query, or none
    pluginNames: ["bearer", "logger"], // plugins to generate
    validation: "zod-runtime", // strict runtime data validation
  },

  // Define your APIs
  apis: {
    petstore: {
      // openapiUrl supports:
      // 1. Backend URL (e.g., "http://localhost:8080/openapi.json")
      // 2. Local File (e.g., "./openapi.json")
      openapiUrl: "http://localhost:8080/openapi.json",
    },
    payment: {
      openapiUrl: "http://api.staging.com/payment/openapi.json",
    },
  },
};

Examples

Example	What it shows
examples/local-file	Generate from a openapi.json on disk
examples/remote-url	Fetch from a running backend + mock server
examples/real-or-fake	Full-stack usage with the mock server
examples/design-patterns	Singleton, Factory, Observer, Builder service patterns

Development

npm install
npm run build
npm test
npm run lint

Built by the open-source community