[Init] Tanstack Query 초기 세팅

package.json

@@ -12,6 +12,7 @@
     "build-storybook": "storybook build"
   },
   "dependencies": {
+    "@tanstack/react-query": "^5.90.16",
     "eslint-import-resolver-typescript": "^4.4.4",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
@@ -22,6 +23,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",
@@ -37,8 +39,8 @@
     "eslint-plugin-react-refresh": "^0.4.24",
     "eslint-plugin-storybook": "^10.1.11",
     "globals": "^16.5.0",
-    "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,9 +2,12 @@
 import { createRoot } from "react-dom/client";
 
 import App from "@app/App";
+import AppProviders from "@app/providers";
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <App />
+    <AppProviders>
+      <App />
+    </AppProviders>
   </StrictMode>
 );

src/app/providers/QueryProvider.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/lib/react-query";
+
+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/app/providers/index.tsx

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

src/shared/lib/react-query/index.ts

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

src/shared/lib/react-query/queryClient.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);
+    },
+  }),
+});