msw-setup

name	msw-setup
description	Scaffold MSW and @msw-mcp/client in a web project for AI-driven dynamic mocks. Use when the user asks to set up MSW, add mocking to a new app, or migrate an existing MSW project.

msw-setup

Project scaffolding for MSW + the MCP client bridge. For runtime handler changes after setup, use the msw-cli skill.

Workflow

1. Run msw-cli setup in the project root (optional: --framework vite).
2. Follow the printed setup guide step by step (detect bundler, install deps, create mocks/, env vars, entry point).
3. Run msw-cli open and set the app's WebSocket URL to the URL from the output.
4. Run msw-cli status after starting the dev server — confirm connected: true (this only proves the WebSocket bridge, not that the first browser requests were intercepted).
5. Hard reload the app and confirm in DevTools → Network that initial API calls are mocked. This catches render-before-mock races that msw-cli status misses.
6. Use msw-cli add (and related commands) to manage mocks at runtime.

Do not duplicate the full setup guide in chat — execute from msw-cli setup output.

Notes

• Ask permission before npm install / npx msw init (as the guide describes).
• The WebSocket URL env var name depends on the framework: NEXT_PUBLIC_MSW_WS_URL (Next.js), VITE_MSW_WS_URL (Vite), or MSW_WS_URL (Rspack/Rsbuild/Webpack) — must match the port from msw-cli open. (MCP_SERVER_URL is accepted as a legacy fallback.)
• Next.js App Router: app/layout.tsx is a Server Component; the MSW bootstrap must be a 'use client' gate so the app subtree does not mount (and fetch) before initMocks() finishes. Follow the guide’s gated MswProvider pattern — do not start MSW in a parallel useEffect while rendering the full tree.
• MCP users can still use /msw-setup in an MCP client; the same guide backs both paths.