mockr

A fast, zero-dependency-on-your-app CLI tool to mock, stub, and proxy HTTP and gRPC APIs — written in Go.

Point your frontend at mockr instead of the real API. Mock only the endpoints you're building. Forward everything else to the real backend. Switch between response scenarios by editing a config file — changes apply instantly.

Install

npm install -D @ridakaddir/mockr

Or use it directly with npx:

npx @ridakaddir/mockr --init

Once installed, the mockr command is available in your project:

npx mockr --init

Quick Start

1. Scaffold a starter config

npx mockr --init

This creates a mockr.toml config file and a stubs/ directory with an example JSON response.

2. Start the mock server

npx mockr

The server starts at http://localhost:4000 by default.

3. Point your frontend at it

Update your API base URL to http://localhost:4000 during development:

// .env.development
VITE_API_URL=http://localhost:4000

// or in your fetch calls
const response = await fetch("http://localhost:4000/api/users");

4. Add to your npm scripts

{
  "scripts": {
    "mock": "mockr --config ./mocks --target https://api.example.com",
    "dev": "concurrently 'npm run mock' 'vite'"
  }
}

Usage

# Start with default config (mockr.toml in current directory)
npx mockr

# Start with a target upstream API
npx mockr --target https://api.example.com

# Start on a custom port
npx mockr --port 3001

# Use a config directory (loads and merges all config files)
npx mockr --config ./mocks

# Strip an API prefix before matching routes
npx mockr --api-prefix /api

# Record responses from a real API
npx mockr --target https://api.example.com --record

# Generate config from an OpenAPI spec
npx mockr generate --spec ./openapi.yaml

# Generate config from a .proto file
npx mockr generate --proto ./service.proto

Features

• Route-based mocking — define routes with named response cases
• Condition routing — route based on request body, query params, headers, or path parameters
• Dynamic file resolution — serve different stubs based on request data
• Reverse proxy fallthrough — unmatched routes forward to the real API
• Hot reload — edit config files and changes apply instantly
• Record mode — proxy a real API and save responses as stub files
• Response templating — {{uuid}}, {{now}}, {{timestamp}} in responses
• OpenAPI generation — generate mockr config from any OpenAPI 3 spec
• gRPC support — mock and proxy gRPC services from .proto files
• Multi-format config — TOML, YAML, or JSON

Config Example

[[routes]]
method = "GET"
path   = "/api/users"
fallback = "success"

  [routes.cases.success]
  status = 200
  file   = "stubs/users.json"

  [routes.cases.empty]
  status = 200
  body   = "[]"

  [routes.cases.error]
  status = 500
  body   = '{"error": "Internal server error"}'

Supported Platforms

| OS | Architecture | Package | | ------- | ------------ | --------------------- | | macOS | ARM64 | @ridakaddir/mockr-darwin-arm64 | | macOS | x64 | @ridakaddir/mockr-darwin-x64 | | Linux | x64 | @ridakaddir/mockr-linux-x64 | | Linux | ARM64 | @ridakaddir/mockr-linux-arm64 | | Windows | x64 | @ridakaddir/mockr-win32-x64 | | Windows | ARM64 | @ridakaddir/mockr-win32-arm64 |

The correct binary for your platform is installed automatically via optionalDependencies.

Documentation

For complete documentation, examples, and configuration reference, visit the main repository.

License

MIT