@uniai-fe/next-providers 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/next-providers",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Next.js State Providers for UNIAI FE Projects",
   "type": "module",
   "private": false,
@@ -10,7 +10,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.30.2",
+  "packageManager": "pnpm@10.33.3",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -46,7 +46,7 @@
     "next": ">= 15",
     "react": ">= 19",
     "react-dom": ">= 19",
-    "@tanstack/react-query": ">= 5",
+    "@tanstack/react-query": ">= 5.100.9",
     "jotai": ">= 2",
     "styled-components": ">= 6",
     "airtable": ">= 0.12",
@@ -72,19 +72,19 @@
     "@uniai-fe/runtime-env": "workspace:*",
     "@uniai-fe/util-jotai": "workspace:*",
     "@uniai-fe/i18n": "workspace:*",
-    "@tanstack/react-query": "^5.90.21",
+    "@tanstack/react-query": "^5.100.9",
     "@types/node": "^24.10.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "airtable": "^0.12.2",
     "eslint": "^9.39.2",
-    "jotai": "^2.18.0",
+    "jotai": "^2.20.0",
     "jotai-tanstack-query": "^0.11.0",
     "next": "^15.5.11",
-    "prettier": "^3.8.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "prettier": "^3.8.3",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "styled-components": "6.1.19",
-    "typescript": "~5.9.3"
+    "typescript": "5.9.3"
   }
 }

package/src/NextRoots.tsx

@@ -1,11 +1,37 @@
 import StyledComponentsRegistry from "./lib/StyledComponentsRegistry";
 import AirtableProvider from "./provider/AirtableProvider";
-import { JotaiProvider } from "./provider/JotaiProvider";
-import { ReactQueryProvider } from "./provider/ReactQueryProvider";
+import {
+  JotaiProvider,
+  type JotaiProviderProps,
+} from "./provider/JotaiProvider";
+import {
+  ReactQueryProvider,
+  type ReactQueryProviderProps,
+} from "./provider/ReactQueryProvider";
 import SetQueryCookie from "./lib/SetQueryCookie";
 import SystemThemeChecker from "./lib/SystemThemeChecker";
 import type { SystemLanguageType } from "@uniai-fe/next-devkit/types";
 
+/**
+ * Next.js Root Layout Provider 구성 props
+ * @typedef {object} NextRootsProps
+ * @property {SystemLanguageType} [locale] AirtableProvider에 전달할 시스템 언어
+ * @property {{ exceptPaths: string[] }} [systemThemeOptions] 시스템 테마 체크 옵션
+ * @property {React.ReactNode} [modalProviders] 서비스별 modal provider 슬롯
+ * @property {Omit<ReactQueryProviderProps, "children">} [reactQueryProviderProps] ReactQueryProvider로 전달할 설정
+ * @property {Omit<JotaiProviderProps, "children">} [jotaiProviderProps] JotaiProvider로 전달할 설정
+ * @property {React.ReactNode} children Root Provider 하위에 배치할 앱 트리
+ */
+type NextRootsProps = {
+  locale?: SystemLanguageType;
+  systemThemeOptions?: { exceptPaths: string[] };
+  modalProviders?: React.ReactNode;
+  reactQueryProviderProps?: Omit<ReactQueryProviderProps, "children">;
+  jotaiProviderProps?: Omit<JotaiProviderProps, "children">;
+
+  children: React.ReactNode;
+};
+
 /**
  * Next.js Root Layout에 적용할 Provider 및 유틸리티 도구 집합
  * @component
@@ -13,38 +39,42 @@ import type { SystemLanguageType } from "@uniai-fe/next-devkit/types";
  * @param {SystemLanguageType} [props.locale] 언어설정; "ko", "en"
  * @param {object} [props.systemThemeOptions] 시스템 테마 체크 옵션
  * @param {string[]} [props.systemThemeOptions.exceptPaths] 테마 체크 제외 경로
- * @param {React.ReactNode} [props.modalProviders] 모달 Provider 슬롯(@uniai-fe/ui-legacy 등 서비스 선택)
+ * @param {object} [props.reactQueryProviderProps] React Query Provider 전달 props
+ * @param {object} [props.jotaiProviderProps] Jotai Provider 전달 props
+ * @param {React.ReactNode} [props.modalProviders] 모달 Provider 슬롯(서비스별 modal provider 선택)
  * @param {() => void} [props.onRouteChange] 경로 변경 시 실행할 콜백(예: 모달 스택 초기화)
  * @param {React.ReactNode} props.children
+ * @returns {React.JSX.Element}
  * @desc
- * - React Query
- * - Jotai
- * - Airtable
- * - System Theme Checker
- * - Router Event Detector
+ * - React Query Provider를 최상위에 두어 하위 Jotai hydration에서 동일 QueryClient를 읽을 수 있게 한다.
+ * - Jotai Provider는 react-query 연동 atom과 서비스별 store를 함께 제공한다.
+ * - StyledComponentsRegistry 내부에서 AirtableProvider와 SystemThemeChecker를 렌더링한다.
+ * - modalProviders는 서비스별 modal stack/provider 조합을 children 옆 슬롯으로 합성한다.
  */
 export default function NextRoots({
   locale = "ko",
   systemThemeOptions,
   modalProviders,
+  reactQueryProviderProps,
+  jotaiProviderProps,
 
   children,
-}: {
-  locale?: SystemLanguageType;
-  systemThemeOptions?: { exceptPaths: string[] };
-  modalProviders?: React.ReactNode;
-
-  children: React.ReactNode;
-}) {
+}: NextRootsProps) {
   return (
-    <ReactQueryProvider>
-      <JotaiProvider>
+    // React Query client는 JotaiHydrateAtoms에서도 같은 인스턴스를 참조해야 하므로 가장 바깥에 둔다.
+    <ReactQueryProvider {...reactQueryProviderProps}>
+      {/* Jotai store 설정은 React Query context 하위에서 적용한다. */}
+      <JotaiProvider {...jotaiProviderProps}>
         <SetQueryCookie />
+        {/* styled-components SSR registry는 실제 화면 트리를 감싸서 style collection 범위를 만든다. */}
         <StyledComponentsRegistry>
+          {/* locale은 Airtable 기반 다국어/환경 데이터 provider에만 전달한다. */}
           <AirtableProvider locale={locale}>
             {children}
+            {/* 서비스별 modal provider는 앱 children과 같은 provider scope에 둔다. */}
             {modalProviders}
           </AirtableProvider>
+          {/* theme check는 provider scope 안에서 route/path 예외 설정을 읽어 실행한다. */}
           <SystemThemeChecker exceptPaths={systemThemeOptions?.exceptPaths} />
         </StyledComponentsRegistry>
       </JotaiProvider>

package/src/provider/JotaiProvider.tsx

@@ -1,22 +1,58 @@
 "use client";
 
+import { useQueryClient } from "@tanstack/react-query";
 import { Provider } from "jotai";
 import { useHydrateAtoms } from "jotai/react/utils";
 import { queryClientAtom } from "jotai-tanstack-query";
-import { getQueryClient } from "./ReactQueryProvider";
+import type { ComponentProps } from "react";
 
-export function JotaiHydrateAtoms({ children }: { children: React.ReactNode }) {
-  useHydrateAtoms([[queryClientAtom, getQueryClient()]]);
+/**
+ * Jotai Provider 전달 props
+ * @typedef {ComponentProps<typeof Provider>} JotaiProviderProps
+ * @property {React.ReactNode} [children] Jotai store 범위 안에서 렌더링할 하위 요소
+ * @property {ReturnType<import("jotai").createStore>} [store] 서비스 또는 테스트에서 주입할 Jotai store 인스턴스
+ */
+export type JotaiProviderProps = ComponentProps<typeof Provider>;
+
+/**
+ * Jotai atom에 React Query client를 연결하는 Hydration 컴포넌트
+ * @component
+ * @param {Pick<JotaiProviderProps, "children">} props
+ * @param {React.ReactNode} [props.children] hydrate 이후 렌더링할 하위 요소
+ * @desc
+ * - ReactQueryProvider 하위에서만 사용한다.
+ * - queryClientAtom에는 React Query Context의 QueryClient와 동일한 인스턴스를 주입한다.
+ * - getQueryClient를 직접 재호출하지 않아 SSR/CSR 간 QueryClient 불일치를 방지한다.
+ */
+export function JotaiHydrateAtoms({
+  children,
+}: Pick<JotaiProviderProps, "children">) {
+  // React Query Provider가 context에 올린 QueryClient 인스턴스를 그대로 읽는다.
+  const queryClient = useQueryClient();
+
+  // jotai-tanstack-query atom이 React Query Provider와 동일한 client를 보도록 hydrate한다.
+  useHydrateAtoms([[queryClientAtom, queryClient]]);
+
+  // Hydration 전용 래퍼이므로 별도 DOM 없이 children만 반환한다.
   return children;
 }
 
 /**
  * Jotai 상태 공급자
  * @component
+ * @param {JotaiProviderProps} props
+ * @param {React.ReactNode} [props.children] Jotai Provider 하위에 배치할 앱 트리
+ * @param {JotaiProviderProps["store"]} [props.store] 외부에서 생성한 Jotai store 인스턴스
+ * @desc
+ * - store가 전달되면 해당 store를 Provider에 그대로 주입한다.
+ * - store가 없으면 Jotai Provider의 기본 store 생성 정책을 따른다.
+ * - 하위 Hydration 컴포넌트에서 queryClientAtom을 React Query Context와 동기화한다.
  */
-export function JotaiProvider({ children }: { children: React.ReactNode }) {
+export function JotaiProvider({ children, store }: JotaiProviderProps) {
   return (
-    <Provider>
+    // 서비스별 store 주입을 허용하되 기본 사용자는 별도 설정 없이 사용할 수 있게 둔다.
+    <Provider store={store}>
+      {/* React Query client atom hydration은 Jotai store 범위 안에서 실행되어야 한다. */}
       <JotaiHydrateAtoms>{children}</JotaiHydrateAtoms>
     </Provider>
   );

package/src/provider/ReactQueryProvider.tsx

@@ -2,10 +2,33 @@
 
 import {
   defaultShouldDehydrateQuery,
-  isServer,
+  environmentManager,
   QueryClient,
   QueryClientProvider,
 } from "@tanstack/react-query";
+import type { QueryClientConfig } from "@tanstack/react-query";
+
+/**
+ * React Query Provider 전달 props
+ * @typedef {object} ReactQueryProviderProps
+ * @property {React.ReactNode} children React Query Provider 하위에 배치할 앱 트리
+ * @property {QueryClient} [queryClient] 외부에서 직접 생성해 주입할 QueryClient 인스턴스
+ * @property {QueryClientConfig} [queryClientConfig] 내부 QueryClient 생성 시 병합할 설정
+ */
+export type ReactQueryProviderProps = {
+  children: React.ReactNode;
+  queryClient?: QueryClient;
+  queryClientConfig?: QueryClientConfig;
+};
+
+/**
+ * QueryClient 기본 옵션 타입
+ * @typedef {NonNullable<QueryClientConfig["defaultOptions"]>} QueryClientDefaultOptions
+ * @desc QueryClientConfig.defaultOptions는 optional이므로 내부 병합 로직에서는 NonNullable 타입으로 고정한다.
+ */
+type QueryClientDefaultOptions = NonNullable<
+  QueryClientConfig["defaultOptions"]
+>;
 
 /**
  * 클라이언트 단에서의 React Query client
@@ -14,47 +37,105 @@ import {
 let browserQueryClient: QueryClient | undefined = undefined;
 
 /**
- * React Query client 생성
- * - 서비스 전역에 적용할 쿼리옵션을 사전에 지정하여 생성
- * @return {QueryClient}
+ * next-providers가 기본으로 제공하는 React Query 전역 옵션
+ * @type {QueryClientDefaultOptions}
+ * @desc
+ * - 서비스별 queryClientConfig가 전달되면 같은 depth의 옵션을 덮어쓴다.
+ * - shouldDehydrateQuery는 pending query dehydration 정책을 기본값 위에 추가한다.
  */
-function makeQueryClient(): QueryClient {
-  return new QueryClient({
-    // react-query 전역 설정
+const defaultQueryClientOptions: QueryClientDefaultOptions = {
+  queries: {
+    // onError: queryErrorHandler,
+    staleTime: 600000,
+    gcTime: 900000, // 기존 cacheTime에서 명칭 변경, 원래 "가비지 콜렉션 시간"을 의미하였음.
+    refetchOnMount: false,
+    refetchOnReconnect: false,
+    refetchOnWindowFocus: false,
+    retry: false,
+  },
+  dehydrate: {
+    // include pending queries in dehydration
+    shouldDehydrateQuery: query =>
+      defaultShouldDehydrateQuery(query) || query.state.status === "pending",
+  },
+};
+
+/**
+ * 기본 QueryClient 옵션과 서비스별 옵션을 병합한다.
+ * @param {QueryClientConfig} [queryClientConfig] 서비스에서 전달한 QueryClient 생성 설정
+ * @returns {QueryClientConfig}
+ * @desc
+ * - 최상위 QueryClientConfig는 서비스 설정을 우선한다.
+ * - defaultOptions 하위의 queries/mutations/hydrate/dehydrate는 depth별로 병합한다.
+ * - 서비스가 dehydrate.shouldDehydrateQuery를 넘기면 기본 pending dehydration 정책을 대체한다.
+ */
+function resolveQueryClientConfig(
+  queryClientConfig?: QueryClientConfig,
+): QueryClientConfig {
+  return {
+    // queryCache, mutationCache, logger 등 최상위 설정은 서비스 설정을 그대로 보존한다.
+    ...queryClientConfig,
     defaultOptions: {
+      // next-providers 기본값을 먼저 놓고, 서비스 defaultOptions로 덮어쓸 수 있게 한다.
+      ...defaultQueryClientOptions,
+      ...queryClientConfig?.defaultOptions,
       queries: {
-        // onError: queryErrorHandler,
-        staleTime: 600000,
-        gcTime: 900000, // 기존 cacheTime에서 명칭 변경, 원래 "가비지 콜렉션 시간"을 의미하였음.
-        refetchOnMount: false,
-        refetchOnReconnect: false,
-        refetchOnWindowFocus: false,
-        retry: false,
+        // query 기본 정책은 유지하되 서비스별 query option이 있으면 우선한다.
+        ...defaultQueryClientOptions.queries,
+        ...queryClientConfig?.defaultOptions?.queries,
+      },
+      mutations: {
+        // mutation 기본 옵션도 future-proofing을 위해 같은 병합 규칙을 적용한다.
+        ...defaultQueryClientOptions.mutations,
+        ...queryClientConfig?.defaultOptions?.mutations,
+      },
+      hydrate: {
+        // hydrate 옵션은 React Query SSR hydration 정책 확장을 위해 분리 병합한다.
+        ...defaultQueryClientOptions.hydrate,
+        ...queryClientConfig?.defaultOptions?.hydrate,
       },
       dehydrate: {
-        // include pending queries in dehydration
-        shouldDehydrateQuery: query =>
-          defaultShouldDehydrateQuery(query) ||
-          query.state.status === "pending",
+        // dehydrate 옵션은 pending query 포함 정책을 기본값으로 제공한다.
+        ...defaultQueryClientOptions.dehydrate,
+        ...queryClientConfig?.defaultOptions?.dehydrate,
       },
     },
-  });
+  };
 }
 
 /**
  * React Query client 생성
+ * - 서비스 전역에 적용할 쿼리옵션을 사전에 지정하여 생성
+ * @param {QueryClientConfig} [queryClientConfig] 기본 옵션과 병합할 QueryClient 생성 설정
  * @return {QueryClient}
  */
-export function getQueryClient(): QueryClient {
-  if (isServer) {
+function makeQueryClient(queryClientConfig?: QueryClientConfig): QueryClient {
+  // QueryClient 생성 전 next-providers 기본값과 서비스 override를 한 번만 병합한다.
+  return new QueryClient(resolveQueryClientConfig(queryClientConfig));
+}
+
+/**
+ * React Query client 생성
+ * @param {QueryClientConfig} [queryClientConfig] 내부 QueryClient 생성 시 사용할 설정
+ * @return {QueryClient}
+ * @desc
+ * - 서버에서는 요청 간 캐시 공유를 피하기 위해 항상 새 QueryClient를 생성한다.
+ * - 브라우저에서는 최초 생성한 QueryClient를 재사용해 초기 suspense 중 client 재생성을 막는다.
+ * - 브라우저 singleton이 이미 생성된 뒤 들어온 queryClientConfig는 반영되지 않는다.
+ */
+export function getQueryClient(
+  queryClientConfig?: QueryClientConfig,
+): QueryClient {
+  if (environmentManager.isServer()) {
     // Server: always make a new query client
-    return makeQueryClient();
+    return makeQueryClient(queryClientConfig);
   } else {
     // Browser: make a new query client if we don't already have one
     // This is very important, so we don't re-make a new client if React
     // suspends during the initial render. This may not be needed if we
     // have a suspense boundary BELOW the creation of the query client
-    if (!browserQueryClient) browserQueryClient = makeQueryClient();
+    if (!browserQueryClient)
+      browserQueryClient = makeQueryClient(queryClientConfig);
     return browserQueryClient;
   }
 }
@@ -62,21 +143,33 @@ export function getQueryClient(): QueryClient {
 /**
  * ReactQuery 상태 공급자
  * @component
+ * @param {ReactQueryProviderProps} props
+ * @param {React.ReactNode} props.children React Query Provider 하위에 배치할 앱 트리
+ * @param {QueryClient} [props.queryClient] 외부에서 직접 생성해 주입할 QueryClient 인스턴스
+ * @param {QueryClientConfig} [props.queryClientConfig] 내부 QueryClient 생성 시 병합할 설정
+ * @desc
+ * - queryClient가 전달되면 내부 singleton보다 전달받은 인스턴스를 우선한다.
+ * - queryClientConfig는 queryClient를 직접 전달하지 않을 때만 내부 생성에 사용한다.
+ * - JotaiProvider는 이 Provider 하위에서 useQueryClient로 동일 인스턴스를 공유한다.
  * @see https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr#prefetching-and-dehydrating-data
  * @see https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr#nesting-server-components
  */
 export function ReactQueryProvider({
   children,
-}: {
-  children: React.ReactNode;
-}) {
+  queryClient,
+  queryClientConfig,
+}: ReactQueryProviderProps) {
   // NOTE: Avoid useState when initializing the query client if you don't
   //       have a suspense boundary between this and the code that may
   //       suspend because React will throw away the client on the initial
   //       render if it suspends and there is no boundary
-  const queryClient = getQueryClient();
+  // 외부 주입 client가 있으면 Provider 전체에서 그 인스턴스를 단일 SOT로 사용한다.
+  const resolvedQueryClient = queryClient ?? getQueryClient(queryClientConfig);
 
   return (
-    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    // React Query context에 올린 client는 JotaiHydrateAtoms에서도 동일하게 참조된다.
+    <QueryClientProvider client={resolvedQueryClient}>
+      {children}
+    </QueryClientProvider>
   );
 }