How does MSW (Mock Service Worker) intercept network requests?

MSW registers a service worker in the browser that intercepts outgoing fetch and XMLHttpRequest calls at the network level. When a request matches a defined handler, the service worker returns the mock response without the request ever leaving the browser. This means your application code—including fetch calls, Axios interceptors, retry logic, and error handling—executes exactly as in production. In Node.js test environments (Vitest, Jest), MSW intercepts using request interception modules instead of service workers, providing the same behavior without a browser.

When should I use json-server vs MSW for local development?

Use json-server when you need a quick, fully functional REST API with CRUD persistence—it creates GET, POST, PUT, PATCH, DELETE endpoints from a JSON file with filtering, pagination, and relationships. Use MSW when you need fine-grained control over responses (error states, delays, conditional logic), when testing specific edge cases, or when you want mocks that work in both browser and test environments. json-server is ideal for prototyping CRUD features; MSW is ideal for debugging, testing error handling, and simulating specific backend behaviors.

How do I reproduce a backend bug locally for frontend debugging?

Capture the exact backend response (status code, headers, body) that triggers the bug—use browser DevTools Network tab or curl. Then create an MSW handler that returns that exact response. For example, if the backend returns malformed JSON with a 200 status, mock it with: new HttpResponse('invalid json', { status: 200, headers: { 'Content-Type': 'application/json' } }). This lets you debug and fix the frontend handling without waiting for the backend fix, and the mock handler becomes a regression test.

How do I toggle between mock and real API without changing code?

Use a query parameter or localStorage flag to conditionally enable mocks. Check for '?mock' in the URL or 'USE_MOCKS' in localStorage, then only start the MSW worker when the flag is set. Add a development toolbar component with a toggle checkbox that sets the flag and reloads the page. This lets developers switch instantly between mock and real backends—mock mode for isolated frontend debugging, real mode for integration testing—without editing configuration files or environment variables.

How should I organize mock files in a project?

Keep mocks in a dedicated src/mocks/ directory with subdirectories for handlers (organized by API domain like users.js, orders.js), fixtures (JSON files with response data), and entry points (browser.js for development, server.js for tests). Version mock files alongside the code that consumes them. When the API contract changes, update handlers and fixtures in the same pull request as the frontend code. This structure makes mocks discoverable, maintainable, and keeps them synchronized with your frontend's actual API usage.

Debugging Client-Side Issues with Mock APIs