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

Define a data array to be returned by the server. Use interfaces from the types/ folder for typing.

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

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

export const ENTITY_MOCK: IEntity[] = [
	{
		id: "1",
		fullName: "John Doe",
		date: "2024-03-22",
		status: "active"
	},
	{
		id: "2",
		fullName: "Jane Smith",
		date: "2024-03-21",
		status: "pending"
	}
];

022. Defining Handlers

Use the msw library to intercept specific URLs. You can also simulate network delay or server errors here.

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

import { HttpResponse, http } from "msw";
import { ENV } from "@/shared/config";
import { ENTITY_MOCK } from "../mock";

export const entityHandlers = [
	http.get(`${ENV.VITE_API_URL}/entity/list`, () => {
		return HttpResponse.json({
			data: ENTITY_MOCK
		});
	}),

	http.post(`${ENV.VITE_API_URL}/entity/update`, async ({ request }) => {
		const body = await request.json();
		return HttpResponse.json({ success: true, data: body });
	})
];

033. Worker Configuration

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);

044. 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
];

055. 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();
};

066. 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>
		);
	});
}

077. Environment Variables

Managing MSW activation via the .env file.

.env

VITE_ENABLE_MSW=true