Usage

Counterfact starts with an OpenAPI document, a local URL, and generated responses. Choose the next guide by the job your frontend, team, or test suite needs—not by a feature checklist.

Frontend workflows

• Getting started — run a local API and make a browser request.
• Routes and custom responses — shape the response a screen needs.
• State — share small in-memory state across routes.
• Hot reload — update handlers without restarting.
• Generated code — understand editable routes and generated types.
• Simulate failures and simulate latency — exercise error, empty, loading, and retry states.

Team and test workflows

• First 10 minutes — a small create/read workflow with one failure.
• Automated integration tests — start and stop a local API in tests.
• Scenario scripts — create repeatable starting states.
• Shared store — coordinate state across API groups.
• AI-assisted implementation and agentic sandbox — give coding agents a bounded, verifiable API task.

Advanced control

• Proxy and hybrid proxy — combine local and upstream paths behind one base URL.
• REPL — inspect or steer a running local API.
• Middleware — add cross-cutting behavior.
• Programmatic API — embed Counterfact in another process.
• Multiple versions — serve more than one API version.
• TypeScript native mode — run route files directly.

Reference and troubleshooting

• Reference — CLI flags, response builders, the $ parameter, and architecture.
• FAQ — state, validation, type safety, and regeneration questions.
• How Counterfact compares — comparison with json-server, WireMock, Prism, Microcks, and MSW.
• Without OpenAPI — the alternative path when no OpenAPI document exists.

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. See the telemetry discussion.