Feat/#9 msw 초기 설정 및 HydrationBoundaryPage 추가

.gitignore

@@ -24,6 +24,7 @@ yarn-debug.log*
 yarn-error.log*
 
 # local env files
+.env
 .env.local
 .env.development.local
 .env.test.local

apps/web/app/HydrationBoundaryPage.tsx

@@ -0,0 +1,58 @@
+import {
+  dehydrate,
+  HydrationBoundary,
+  QueryClient,
+} from '@tanstack/react-query'
+import { ReactNode } from 'react'
+
+/**
+ * React Query 쿼리 구성 타입
+ *
+ * @property queryKey - React Query에서 사용할 쿼리 키
+ * @property queryFn  - 데이터를 가져오는 비동기 함수
+ */
+type QueryConfig = {
+  queryKey: string[]
+  queryFn: () => Promise<unknown>
+}
+
+/**
+ * 서버 컴포넌트에서 React Query 쿼리를 미리 요청(prefetch)한 뒤,
+ * dehydrate 상태를 클라이언트에 전달하기 위한 컴포넌트.
+ *
+ * @example
+ * ```tsx
+ * <HydrationBoundaryPage
+ *   queries={[
+ *     { queryKey: ['user'], queryFn: fetchUser },
+ *     { queryKey: ['posts'], queryFn: fetchPosts },
+ *   ]}
+ * >
+ *   <MyPage />
+ * </HydrationBoundaryPage>
+ * ```
+ *
+ * @param queries - 사전 요청할 쿼리들의 배열
+ * @param children - HydrationBoundary로 감쌀 React 노드
+ */
+export const HydrationBoundaryPage = async ({
+  queries,
+  children,
+}: {
+  queries: QueryConfig[]
+  children: ReactNode
+}) => {
+  const queryClient = new QueryClient()
+
+  await Promise.all(
+    queries.map(({ queryKey, queryFn }) =>
+      queryClient.prefetchQuery({ queryKey, queryFn }),
+    ),
+  )
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      {children}
+    </HydrationBoundary>
+  )
+}

apps/web/app/_constants/path.ts

@@ -0,0 +1,3 @@
+export const API_PATH = {
+  CATEGORY: '/categories',
+}

apps/web/app/_lib/axiosInstance.ts

@@ -0,0 +1,8 @@
+import axios from 'axios'
+
+const axiosInstance = axios.create({
+  baseURL: process.env.NEXT_PUBLIC_API_URL,
+  withCredentials: true,
+})
+
+export default axiosInstance

apps/web/app/_mocks/MSWProvider.tsx

@@ -0,0 +1,22 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { initBrowserMSW } from '@/_mocks/initMSW'
+
+export function MSWProvider({ children }: { children: React.ReactNode }) {
+  const isDev = process.env.NODE_ENV === 'development'
+  const [mswReady, setMSWReady] = useState(!isDev)
+
+  useEffect(() => {
+    if (!isDev || mswReady) return
+    const init = async () => {
+      await initBrowserMSW()
+      setMSWReady(true)
+    }
+    init()
+  }, [isDev, mswReady])
+
+  if (!mswReady) return null
+
+  return <>{children}</>
+}

apps/web/app/_mocks/data/category.ts

@@ -0,0 +1,17 @@
+export const category = [
+  { id: 1, name: '치킨', iconKey: 'chicken' },
+  { id: 2, name: '햄버거', iconKey: 'burger' },
+  { id: 3, name: '한식', iconKey: 'korean' },
+  { id: 4, name: '분식', iconKey: 'bunsik' },
+  { id: 5, name: '중식', iconKey: 'chinese' },
+  { id: 6, name: '양식', iconKey: 'western' },
+  { id: 7, name: '샐러드', iconKey: 'salad' },
+  { id: 8, name: '일식', iconKey: 'japanese' },
+  { id: 9, name: '카페', iconKey: 'cafe' },
+  { id: 10, name: '피자', iconKey: 'pizza' },
+  { id: 11, name: '멕시칸', iconKey: 'mexican' },
+  { id: 12, name: '아시안', iconKey: 'asian' },
+  { id: 13, name: '찜·탕', iconKey: 'soup' },
+  { id: 14, name: '고기·구이', iconKey: 'meat' },
+  { id: 15, name: '도시락', iconKey: 'lunchbox' },
+]

apps/web/app/_mocks/handlers/categoryHandlers.ts

@@ -0,0 +1,15 @@
+import { http, HttpResponse } from 'msw'
+import { category } from '../data/category'
+import { API_PATH } from '@/_constants/path'
+
+const BASE_URL = process.env.NEXT_PUBLIC_API_URL || ''
+
+const addBaseUrl = (path: string) => {
+  return `${BASE_URL}${path}`
+}
+
+export const CategoryHandlers = [
+  http.get(addBaseUrl(API_PATH.CATEGORY), () => {
+    return HttpResponse.json(category)
+  }),
+]

apps/web/app/_mocks/handlers/index.ts

@@ -0,0 +1,3 @@
+import { CategoryHandlers } from '@/_mocks/handlers/categoryHandlers'
+
+export const handlers = [...CategoryHandlers]

apps/web/app/_mocks/initMSW.ts

@@ -0,0 +1,21 @@
+export const initServerMSW = async () => {
+  // 서버에서만 실행되는 MSW 초기화
+  if (typeof window === 'undefined' && process.env.NODE_ENV === 'development') {
+    import('./server').then(({ server }) => {
+      server.listen({
+        onUnhandledRequest: 'warn',
+      })
+      console.log('✅ MSW 서버 시작됨')
+    })
+  }
+}
+
+export const initBrowserMSW = async () => {
+  if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+    const { worker } = await import('./worker')
+    await worker.start({
+      onUnhandledRequest: 'bypass',
+    })
+    console.log('✅ MSW 브라우저 시작됨')
+  }
+}

apps/web/app/_mocks/server.ts

@@ -0,0 +1,4 @@
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)

apps/web/app/_mocks/worker.ts

@@ -0,0 +1,4 @@
+import { setupWorker } from 'msw/browser'
+import { handlers } from './handlers'
+
+export const worker = setupWorker(...handlers)

apps/web/app/layout.tsx

@@ -3,6 +3,8 @@ import './globals.css'
 import type { Metadata } from 'next'
 import QueryProvider from './QueryClientProvider'
 import localFont from 'next/font/local'
+import { initServerMSW } from '@/_mocks/initMSW'
+import { MSWProvider } from '@/_mocks/MSWProvider'
 import { Column } from '@repo/ui/components/Layout/Column'
 
 export const metadata: Metadata = {
@@ -16,21 +18,25 @@ const pretendard = localFont({
   weight: '45 920',
 })
 
-export default function RootLayout({
+export default async function RootLayout({
   children,
 }: {
   children: React.ReactNode
 }) {
+  await initServerMSW()
+
   return (
-    <html lang='ko'>
+    <html lang='ko' suppressHydrationWarning={true}>
       <body className={pretendard.className}>
-        <QueryProvider>
-          <div className={'flex h-svh justify-center bg-gray-50'}>
-            <Column className={'relative w-[450px] max-w-[450px] bg-white'}>
-              {children}
-            </Column>
-          </div>
-        </QueryProvider>
+        <MSWProvider>
+          <QueryProvider>
+            <div className={'flex h-svh justify-center bg-gray-50'}>
+              <Column className={'relative w-[450px] max-w-[450px] bg-white'}>
+                {children}
+              </Column>
+            </div>
+          </QueryProvider>
+        </MSWProvider>
       </body>
     </html>
   )

apps/web/package.json

@@ -3,6 +3,9 @@
   "version": "1.0.0",
   "type": "module",
   "private": true,
+  "msw": {
+    "workerDirectory": "./public"
+  },
   "scripts": {
     "dev": "next dev --port 3000 --turbopack",
     "build": "next build",
@@ -17,6 +20,7 @@
     "@suspensive/react": "^3.3.2",
     "@tanstack/react-query": "^5.84.1",
     "@tanstack/react-query-devtools": "^5.84.1",
+    "axios": "^1.11.0",
     "motion": "^12.23.12",
     "next": "^15.4.2",
     "react": "^19.1.0",
@@ -40,10 +44,11 @@
     "autoprefixer": "^10.4.20",
     "eslint": "^9.32.0",
     "jsdom": "^26.1.0",
+    "msw": "^2.10.5",
     "postcss": "^8.5.3",
     "tailwindcss": "^4.1.5",
     "typescript": "5.8.2",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4"
   }
-}
+}