snaperro

A mock proxy server that records and replays responses from multiple APIs to streamline development and testing.

Name Origin

• snap: snapshot, quickly capture
• perro: Spanish for "dog"
• The image of "a faithful dog that fetches data"

Features

• 4 Modes: Proxy (passthrough) / Record (capture) / Mock (playback) / Smart (auto)
• Parameter Matching: Accurate matching by path parameters and query parameters
• State Persistence: Mode and scenario settings persist across server restarts
• TypeScript Configuration: Type-safe configuration files

Why snaperro?

Are you facing these problems during development?

• Depending on multiple APIs, making environment setup difficult
• Local development stops due to external API outages
• Preparing test data is tedious
• "I want to reproduce this state" but manually operating each time is a hassle

snaperro is a mock proxy server that saves API responses as "snapshots" and can replay them anytime.

---

For Users

Quick Start

# Install
npm install -D snaperro

# Initialize (generates .snaperro/, snaperro.config.ts)
npx snaperro init

# Start server
npx snaperro start

Demo

We provide a demo environment where you can experience snaperro in action.

npx snaperro demo

Your browser will open http://localhost:3333/__snaperro__/demo.

Features You Can Try

Feature	Description
Mode Switching	Experience the differences between Proxy/Record/Mock modes
Path Parameter	Save and return different responses for each ID with /users/:id
Query String	Save and return different responses for each query with /posts?userId=1
Nested Resource	Fetch nested resources with /posts/:id/comments

For detailed management (scenarios/files/JSON editing), use the GUI (/__snaperro__/client).

Built-in APIs

The following APIs are available without configuration:

API	Target	Routes
jsonPlaceholder	https://jsonplaceholder.typicode.com	/users, /posts, /comments, etc.

These are used by the demo page and can be overridden in your config if needed.

Web GUI

Intuitively operate snaperro from your browser.

Access

http://localhost:3333/__snaperro__/client

The browser opens automatically when the server starts.

Features

Feature	Description
Mode Switch	Switch between Proxy/Record/Mock with one click
Scenario Management	Create, delete, duplicate, and rename scenarios
File Management	List and delete recorded JSON files
JSON Editor	View and edit responses
Real-time Updates	Instantly reflect state changes via SSE

Configuration File

snaperro.config.ts

import { defineConfig } from 'snaperro'

export default defineConfig({
  port: 3333,

  apis: {
    userService: {
      name: "User Service",
      target: "https://api.example.com",
      headers: {
        "X-Api-Key": process.env.API_KEY!,
      },
      routes: [
        "/api/users",
        "/api/users/:id",
        "/api/users/:id/profile",
      ],
    },

    orderService: {
      name: "Order Service",
      target: "https://order-api.example.com",
      routes: [
        "/api/orders",
        "/api/orders/:id",
        "/api/users/:userId/orders",
      ],
    },
  },
})

.env

# Sensitive information such as API keys
API_KEY=your-api-key-here

Configuration Options

Option	Type	Description
port	number	Server port (default: 3333)
filesDir	string	File storage directory (default: .snaperro/files)
mockFallback	string	Fallback behavior when mock file is not found (default: "404")
maskRequestHeaders	string[]	Headers to mask when recording (applied to all APIs)
apis	object	API definitions object

API Definition

Option	Type	Required	Description
name	string	Yes	API display name
target	string	Yes	Proxy target URL
routes	string[]	Yes	Matching route patterns
headers	object	No	Headers to add
maskRequestHeaders	string[]	No	Headers to mask when recording

Upstream Proxy

If you're behind a corporate proxy, configure upstream proxy settings:

Via config file:

export default defineConfig({
  upstreamProxy: {
    url: "http://proxy.company.com:8080",
  },
  // ...
})

Via environment variable:

export HTTPS_PROXY=http://proxy.company.com:8080
# or with authentication
export HTTPS_PROXY=http://username:[email protected]:8080

Config file takes priority over environment variables.

Important: When using an upstream proxy, add localhost to NO_PROXY to ensure local requests bypass the proxy:

export NO_PROXY=localhost,127.0.0.1

CLI Commands

Command	Description
npx snaperro init	Initialize project
npx snaperro start	Start server
npx snaperro start -p 4000	Start with specified port
npx snaperro demo	Start demo environment
npx snaperro postman	Export Postman collection

init Process

1. Create .snaperro/ directory
2. Create .snaperro/files/ directory
3. Create snaperro.config.ts template (if it doesn't exist)
4. Add .snaperro/ to .gitignore

start Options

Option	Description
-p, --port <port>	Specify port number
-c, --config <path>	Specify config file path
-e, --env <path>	Specify env file path (default: .env in config directory)
-v, --verbose	Show detailed logs

4 Modes

Mode	Real API	Save JSON	Returns
Proxy	Access	No	Real response
Record	Access	Yes	Real response
Mock	No access	No	Saved JSON
Smart	Conditional	Conditional	Mock or Real

Proxy Mode

Connects to the actual API with headers (API Key, etc.) defined in the configuration file.

Request → snaperro → Real API → Response

Record Mode

Connects to the actual API while recording responses to JSON files.

Request → snaperro → Real API → Response
                ↓
           Save to JSON file

• Same endpoint, same parameters → Overwrite
• Same endpoint, different parameters → Create new file

Mock Mode

Returns responses from saved JSON files. Does not access the actual API.

Request → snaperro → Search JSON files → Response

Smart Mode

Automatically returns mock data if it exists, otherwise proxies to the real server and records the response.

Request → snaperro → Search mock files
                ↓
         Found? → Yes → Return mock (no API access)
                ↓ No
         Proxy to real API & Record
                ↓
         Return response

This is the recommended mode for daily development:

• Prevents unnecessary API calls when mock data already exists
• Automatically records new endpoints
• Reduces API rate limit concerns

Mock Fallback Behavior

When a mock file is not found, you can configure the fallback behavior with mockFallback:

Value	Description
"404"	Return 404 error (default)
"proxy"	Forward request to real server
"proxy&record"	Forward to real server and record the response

export default defineConfig({
  mockFallback: "proxy&record",  // Fallback to proxy and record
  // ...
})

What is a Scenario?

A "scenario" is a folder that manages a set of mock data.

.snaperro/
├── state.json              ← Server state (mode, scenario)
└── files/
    ├── normal-full/           ← Scenario "normal-full"
    │   ├── api_users_001.json
    │   ├── api_users_{id}_001.json
    │   └── api_orders_001.json
    ├── empty-data/             ← Scenario "empty-data"
    │   └── api_users_001.json
    └── error-cases/             ← Scenario "error-cases"
        └── api_users_001.json

By switching scenarios, you can use different mock data sets. The previous mode and scenario are restored even after server restart.

Route Definition and Matching

Path Parameters

Define path parameters with :param format.

routes: [
  "/api/users",           // Exact match
  "/api/users/:id",       // :id is a parameter
  "/api/users/:id/orders/:orderId",  // Multiple parameters
]

Matching Examples

routes: ["/api/users/:id"]

Request	Match	pathParams
/api/users/123	Yes	{ id: "123" }
/api/users/abc	Yes	{ id: "abc" }
/api/users	No	-
/api/users/123/profile	No	-

Record Mode Behavior

• Same parameter request → Overwrite existing file
• New parameter request → Create new file

Mock Mode Behavior

• Return file with exact match of path parameters and query parameters
• Return 404 error if no matching file

File Structure

your-project/
├── snaperro.config.ts     # Config file (Git managed)
├── .env                   # Sensitive info (Not Git managed)
├── .env.example           # Env template (Git managed)
└── .snaperro/             # Recorded data (Not Git managed)
    ├── state.json         # Server state
    └── files/
        ├── normal-full/
        │   ├── api_users_001.json
        │   └── api_users_{id}_001.json
        └── error-cases/
            └── api_users_001.json

SSE (Server-Sent Events)

An SSE endpoint is provided for GUI and clients to detect state changes in real-time.

Endpoint

GET /__snaperro__/events

Verification

# curl
curl -N http://localhost:3333/__snaperro__/events

# Browser console
const es = new EventSource('http://localhost:3333/__snaperro__/events');
es.addEventListener('connected', (e) => console.log(JSON.parse(e.data)));
es.addEventListener('file_created', (e) => console.log(JSON.parse(e.data)));

Event Types

Event	Description
connected	Connection complete (includes initial state)
mode_changed	Mode changed
scenario_changed	Scenario switched
file_created	File created (during recording)
file_updated	File updated
file_deleted	File deleted
scenario_created	Scenario created
scenario_deleted	Scenario deleted
scenario_renamed	Scenario renamed

---

For Developers

Local Development (Testing CLI without npm publish)

# 1. Install dependencies
pnpm install

# 2. Build
pnpm build

# 3. Run CLI locally
npx . init
npx . start

During development (run directly without build):

npx tsx src/cli/index.ts init
npx tsx src/cli/index.ts start

Development Commands

When you want to:

Goal	Command
Watch code changes during development	pnpm dev
Build for production	pnpm build
Run tests	pnpm test
Run tests in watch mode	pnpm test:watch
Format code	pnpm format
Check type errors	pnpm type-check
Develop GUI	pnpm dev:client
Build GUI	pnpm build:client
Develop demo	pnpm dev:demo
Build demo	pnpm build:demo

Project Structure

snaperro/
├── cli/                      # CLI commands
│   ├── index.ts
│   └── commands/
│       ├── init.ts
│       ├── postman.ts
│       └── start.ts
├── server/                   # Hono server
│   ├── handlers/
│   │   ├── handler.ts
│   │   ├── proxy.ts
│   │   ├── recorder.ts
│   │   ├── mocker.ts
│   │   └── control-api.ts
│   ├── core/
│   │   ├── config.ts
│   │   ├── state.ts
│   │   ├── storage.ts
│   │   └── matcher.ts
│   └── types/
├── client/                   # React GUI
│   └── src/
├── demo/                     # Demo application
│   └── src/
└── doc/                      # Documentation

---

Tech Stack

Category	Choice
Server	Hono
CLI	Commander
GUI	React + Tailwind CSS
Schema	Zod
Logging	Consola
Path Matching	Picomatch
Build	tsup, Vite
Linter/Formatter	Biome
Test	Vitest

Requirements

• Node.js 18 or higher
• tsx must be installed (peerDependencies)

License

MIT