[Init] Tanstack Query 초기 세팅

package.json

@@ -22,6 +22,7 @@
     ]
   },
   "dependencies": {
+    "@tanstack/react-query": "^5.90.16",
     "@vanilla-extract/css": "^1.18.0",
     "@vanilla-extract/vite-plugin": "^5.1.4",
     "eslint-import-resolver-typescript": "^4.4.4",
@@ -36,6 +37,7 @@
     "@storybook/addon-docs": "^10.1.11",
     "@storybook/react-vite": "^10.1.11",
     "@svgr/plugin-svgo": "^8.1.0",
+    "@tanstack/react-query-devtools": "^5.91.2",
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",
@@ -55,6 +57,7 @@
     "lint-staged": "^16.2.7",
     "storybook": "^10.1.11",
     "prettier": "3.7.4",
+    "storybook": "^10.1.11",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.46.4",
     "vite": "^7.2.4",

src/app/main.tsx

@@ -2,6 +2,7 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 
 import App from "@app/App";
+import AppProviders from "@app/providers";
 
 import "@app/styles/global.css";
 
@@ -10,6 +11,8 @@ if (!rootEl) throw new Error('Root element "#root" not found');
 
 createRoot(rootEl).render(
   <StrictMode>
-    <App />
+    <AppProviders>
+      <App />
+    </AppProviders>
   </StrictMode>
 );

src/app/providers/index.tsx

@@ -0,0 +1,7 @@
+import type { PropsWithChildren } from "react";
+
+import QueryProvider from "./query-provider";
+
+export default function AppProviders({ children }: PropsWithChildren) {
+  return <QueryProvider>{children}</QueryProvider>;
+}

src/app/providers/query-provider.tsx

@@ -0,0 +1,26 @@
+import type { PropsWithChildren } from "react";
+import { Suspense, lazy } from "react";
+import { QueryClientProvider } from "@tanstack/react-query";
+
+import { queryClient } from "@/shared/api";
+
+const ReactQueryDevtools = import.meta.env.DEV
+  ? lazy(async () => {
+      const mod = await import("@tanstack/react-query-devtools");
+      return { default: mod.ReactQueryDevtools };
+    })
+  : null;
+
+export default function QueryProvider({ children }: PropsWithChildren) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+
+      {import.meta.env.DEV && ReactQueryDevtools ? (
+        <Suspense fallback={null}>
+          <ReactQueryDevtools initialIsOpen={false} />
+        </Suspense>
+      ) : null}
+    </QueryClientProvider>
+  );
+}

src/shared/api/index.ts

@@ -0,0 +1 @@
+export { queryClient } from "./query-client";

src/shared/api/query-client.ts

@@ -0,0 +1,36 @@
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 0,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: true,
+
+      staleTime: 30 * 1000,
+      gcTime: 10 * 60 * 1000,
+
+      throwOnError: false,
+    },
+    mutations: {
+      retry: 0,
+      throwOnError: false,
+    },
+  },
+
+  queryCache: new QueryCache({
+    onError: (error: unknown) => {
+      // TODO: API 초기 세팅 PR merge 후 공통 에러 핸들러 연결
+      // handleApiError(error);
+      console.error(error);
+    },
+  }),
+
+  mutationCache: new MutationCache({
+    onError: (error: unknown) => {
+      // TODO: API 초기 세팅 PR merge 후 공통 에러 핸들러 연결
+      // handleApiError(error);
+      console.error(error);
+    },
+  }),
+});