Find your workflow

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.

New to the terminology? Read How Counterfact fits together, including what an API group shares.

For feature explanations, use the user manual. For exact options and signatures, use the API reference.

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.
• Failures, latency, and edge cases — 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.
• Model the workflow — keep state small and document supported behavior.
• Test context logic — verify domain behavior independently of HTTP adapters.
• Payment retry and reset — run decline, recovery, permission, and isolation assertions.
• Contract-change check — regenerate, observe a type error, and repair a handler.
• Shared store — coordinate state across API groups.
• Third-party SDK against a local API — redirect the Stripe Node SDK, exercise a rate limit, and recover.
• AI-assisted implementation and agentic sandbox — give coding agents a specific task and tests you can run yourself.

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 — understand native loading and installed-CLI limitations.

Reference and troubleshooting

• API 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 sends usage events to PostHog: startup options, hot-reload change categories (route/context/OpenAPI), and REPL command names. Events include the Node.js version, operating system, and architecture; startup events also include the Counterfact version and a subset of resolved options such as port and enabled actions. API file locations are SHA-256 hashed before sending. REPL command arguments are not included in these events.

To disable Counterfact telemetry, set COUNTERFACT_TELEMETRY_DISABLED=true before starting the process. For example, in a POSIX shell:

export COUNTERFACT_TELEMETRY_DISABLED=true
npx counterfact@latest ./openapi.yaml api

In PowerShell, use $env:COUNTERFACT_TELEMETRY_DISABLED = "true" before the command. Telemetry is also disabled when the CI environment variable is set. This switch controls Counterfact process telemetry; it does not configure analytics on this website.

See Feedback, Telemetry, and Privacy for the project discussion.