Mock Server (MSW)

A tool for intercepting network requests at the browser level. Allows frontend development independent of backend readiness using typed mocks.

API Mocking (MSW Documentation)

Benefits: Allows testing error scenarios, network delays, and various data states without a real backend.

Mock Layer Structure

Naming and Location Rules

Handlers:
Located in src/entities/[entity-name]/handlers/. Files named [entity-name].handlers.ts. Contain logic for intercepting entity-specific requests.
Mocks:
Located in src/entities/[entity-name]/mock/. Files named [entity-name].mock.ts. Contain static or dynamic data simulating a server response.
Configuration:
General MSW settings are in src/shared/api/msw/. All handlers are registered in handlers.ts.

011. Creating Mocks (backend DTO seed)

Define seed data in backend DTO shape. Handlers must not return frontend models if RTK converters run in transformResponse.

entities/[entity-name]/mock/[entity-name].mock.ts

import type { TEntityBackend } from "../types";

/** Seed in backend DTO shape — never frontend models */
export const ENTITY_MOCK: TEntityBackend[] = [
	{
		id: "1",
		full_name: "John Doe",
		created_at: "2024-03-22T10:00:00Z",
		status_code: "active"
	},
	{
		id: "2",
		full_name: "Jane Smith",
		created_at: "2024-03-21T10:00:00Z",
		status_code: "pending"
	}
];

01b1b. Optional Mock Store

Mutable store with reset for mutations and Vitest isolation. Skip for read-only static lists.

entities/[entity-name]/mock/[entity-name].store.ts

import type { TEntityBackend, TEntitiesBackend } from "../types";
import { ENTITY_MOCK } from "./entity.mock";

const createStore = () =>
	new Map(ENTITY_MOCK.map((item) => [item.id, structuredClone(item)]));

let store = createStore();

/** Call from Vitest beforeEach for isolation — optional for read-only mocks */
export const resetEntityStore = () => {
	store = createStore();
};

export const listEntitiesBackend = (): TEntitiesBackend => ({
	items: [...store.values()],
	total_count: store.size
});

022. createMockHandler Utils

Shared factory using VITE_BASE_URL, delay (0 in tests), JSON body parse, and validation error helpers.

shared/api/msw/utils.ts

import { HttpResponse, delay, http } from "msw";
import { ENV } from "@/shared/config";

const BASE_URL = (ENV.VITE_BASE_URL || "").replace(/\/$/, "");
const MOCK_RESPONSE_DELAY_MS = import.meta.env.MODE === "test" ? 0 : 500;

export const createMockHandler = (endpoint, resolver) =>
	http[endpoint.method.toLowerCase()](
		`${BASE_URL}${endpoint.url}`,
		async ({ request, params }) => {
			await delay(MOCK_RESPONSE_DELAY_MS);
			let body;
			try {
				body = await request.clone().json();
			} catch {
				/* no body */
			}
			return resolver({
				body,
				query: new URL(request.url).searchParams,
				params,
				request
			});
		}
	);

export const mockValidationError = (loc, msg) =>
	HttpResponse.json(
		{ detail: [{ loc, msg, type: "value_error" }] },
		{ status: 422 }
	);

023. Defining Handlers

Use createMockHandler and return backend envelopes / error contracts matching the real API.

entities/[entity-name]/handlers/[entity-name].handlers.ts

import { HttpResponse } from "msw";
import {
	createMockHandler,
	mockValidationError
} from "@/shared/api/msw/utils";
import { listEntitiesBackend } from "../mock";

/**
 * Return backend DTO. RTK transformResponse + converters map to
 * IPaginationResponse / domain models — do not return { data, total } here.
 */
export const entityHandlers = [
	createMockHandler(
		{ url: "/entities", method: "GET", _types: { body: undefined } },
		({ query }) => {
			const page = Number(query.get("page") ?? 1);
			if (!Number.isInteger(page) || page < 1) {
				return mockValidationError(["query", "page"], "Invalid page");
			}
			return HttpResponse.json(listEntitiesBackend());
		}
	)
];

034. Browser Worker

Create a worker instance in shared/api/msw/browser.ts to intercept browser requests.

shared/api/msw/browser.ts

import { setupWorker } from "msw/browser";
import { handlers } from "./handlers";

export const worker = setupWorker(...handlers);

03b4b. Node Server (Vitest)

Create setupServer in shared/api/msw/server.ts for unit/integration tests.

shared/api/msw/server.ts

import { setupServer } from "msw/node";
import { handlers } from "./handlers";

/** Vitest / Node tests */
export const server = setupServer(...handlers);

045. Handlers Registry

Assemble handlers from all entities into a single array in shared/api/msw/handlers.ts.

shared/api/msw/handlers.ts

import { entityOneHandlers } from "@/entities/entity-one/handlers";
import { entityTwoHandlers } from "@/entities/entity-two/handlers";

export const handlers = [
	...entityOneHandlers,
	...entityTwoHandlers
];

056. App Initialization

Create an async startup function in app/init/msw.ts that checks environment flags.

app/init/msw.ts

import { ENV } from "@/shared/config";

export const initMsw = async () => {
	if (import.meta.env.DEV && ENV.VITE_ENABLE_MSW === "true") {
		const { worker } = await import("@/shared/api/msw/browser");
		return worker.start({
			onUnhandledRequest: "bypass"
		});
	}
	return Promise.resolve();
};

067. Entry Point (Main)

Wait for MSW to start before rendering the application in src/main.tsx.

main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { initMsw } from "./app/init/msw";
import App from "./app";

const container = document.getElementById("root");

if (container) {
	const root = createRoot(container);

	initMsw().then(() => {
		root.render(
			<StrictMode>
				<App />
			</StrictMode>
		);
	});
}

078. Environment Variables

Managing MSW activation via the .env file (VITE_ENABLE_MSW, VITE_BASE_URL).

.env

VITE_ENABLE_MSW=true