Installation & Setup
This guide walks you through installing Mocking GUI and setting up the initial configuration for your project.
📋 Requirements
- Node.js >= 22.0.0
- pnpm >= 9.0.0
- React >= 19.2.1
1. Install Package
Install the package as a development dependency (devDependencies).
pnpm add -D @kakaocloud/mocking-gui2. Initialize MSW
Mocking GUI uses MSW (Mock Service Worker) internally. You need to create a Service Worker script in your project's static file directory (e.g., public/).
npx msw init <PUBLIC_DIR> [options]Note:
public/is the standard static file directory. Adjust the path according to your framework's structure (e.g., Next.js, Vite).
3. Create Configuration File (config.ts)
Create a configuration file in your project root or mocks/ directory.
// config.ts
import type { MockingConfig } from '@kakaocloud/mocking-gui';
export const mockConfig: MockingConfig = {
// 1. Mocks: Define manual handlers (Optional)
mocks: [
{
name: 'Get User',
url: `${BASE_PATH}/api/user`,
method: 'get',
responseVariants: [
{
name: 'Success',
status: 200,
body: { id: 1, name: 'John Doe' },
},
],
},
],
// 2. Swagger: Automatically load Swagger JSON (Optional)
// Refer to the 'Swagger Management' guide for details.
swagger: [],
// 3. Worker: Service Worker configuration (Optional)
// Required if the application uses a base path (e.g., /services)
worker: {
serviceWorker: {
url: `${BASE_PATH}/mockServiceWorker.js`,
options: {
scope: './',
},
},
},
};4. Framework Integration
WARNING
Always combine it with a NODE_ENV === 'development' check. If you rely solely on the env variable, the Mocking GUI Panel could be accidentally exposed in staging or production environments.
There are two recommended patterns depending on your needs:
- Always enable in development — If you want Mocking GUI active whenever
NODE_ENV === 'development', anIS_DEVcheck alone is sufficient. No extra env variable needed. - Opt-in within development — If you want to control whether Mocking GUI is enabled even in a development environment (e.g., some developers on the team prefer it off by default), combine
IS_DEVwith an additional env variable likeVITE_ENABLE_MOCKING_GUIorNEXT_PUBLIC_ENABLE_MOCKING_GUI.
TIP
Not sure which to choose? Start with the IS_DEV-only approach. Add an env variable later if your team needs finer control.
React (Vite, CRA)
Add MockingGUIBoundary to your top-level component (e.g., App.tsx or main.tsx).
import { MockingGUIBoundary } from '@kakaocloud/mocking-gui/browser';
import { mockConfig } from './config';
const IS_DEV = import.meta.env.DEV;
function App() {
const content = <AppContent />;
return IS_DEV ? <MockingGUIBoundary config={mockConfig}>{content}</MockingGUIBoundary> : content;
}# .env.local
VITE_ENABLE_MOCKING_GUI=trueNext.js (App Router)
In Next.js App Router, you need to create a separate Client Component wrapper for compatibility with Server Components.
- Create Client Component Wrapper (
components/MockingGUIWrapper.tsx)
'use client';
import dynamic from 'next/dynamic';
import { mockConfig } from '@/mocks/config';
// Use dynamic import to prevent loading browser-only modules during SSR
const MockingGUIBoundary = dynamic(
() => import('@kakaocloud/mocking-gui/browser').then(module => module.MockingGUIBoundary),
{ ssr: false },
);
export default function MockingGUIWrapper({ children }: React.PropsWithChildren) {
return <MockingGUIBoundary config={mockConfig}>{children}</MockingGUIBoundary>;
}- Apply to Root Layout (
app/layout.tsx)
import MockingGUIWrapper from '@/components/MockingGUIWrapper';
const IS_DEV = process.env.NODE_ENV === 'development';
export default function RootLayout({ children }) {
return (
<html>
<body>{IS_DEV ? <MockingGUIWrapper>{children}</MockingGUIWrapper> : children}</body>
</html>
);
}