Usage
Counterfact is three tools in one:
- a code generator that converts an OpenAPI document to TypeScript route files
- a mock server optimized for front-end development workflows
- a live REPL for inspecting and manipulating server state at runtime
Choose the path that matches what you’re building, then dive deeper when you need a specific feature or workflow.
Getting started
New to Counterfact? Begin with the Getting Started guide for a step-by-step walkthrough.
Features
| Feature | Description |
|---|---|
| Generated code | How Counterfact generates TypeScript from your OpenAPI spec |
| Routes | Writing route handlers, building responses, reading request data |
| State (contexts and shared store) | Sharing in-memory state across routes and API groups |
| Hot reload | Live file updates without restarting the server |
| REPL | Interactive terminal for runtime inspection and control |
| Proxy | Mix real backend calls with mocked endpoints |
| Middleware | Cross-cutting request/response logic |
| TypeScript native mode | Run route files directly without a compilation step |
| Programmatic API | Embed Counterfact in test suites with Playwright, Cypress, etc. |
| Without OpenAPI | Use Counterfact without an OpenAPI document |
| Multiple versions | Serve multiple API versions simultaneously from a single process |
Patterns
Patterns are practical ways to use Counterfact for common API development and testing jobs.
See the patterns index for the full list.
Reference
Complete technical reference: the $ parameter API, CLI flags, architecture overview, and more.
FAQ
Common questions about state, types, hot reload, code generation, and regeneration.
→ FAQ
Telemetry and privacy
Counterfact records startup options, hot-reload change categories (route/context/OpenAPI), and REPL command names. API file locations are hashed and command arguments are never sent.
How it compares
Side-by-side comparison with json-server, WireMock, Prism, Microcks, and MSW.