@uniai-fe/next-providers 0.1.1

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2025 UNIAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project includes third-party software governed by additional licenses,
+including Apache License 2.0. Refer to `THIRD_PARTY_NOTICES.md` for the full
+text of those notices and any required attributions.

package/README.md

@@ -0,0 +1,3 @@
+# client / next-providers
+
+상태관리 도구 \<Provider /> 및 보조 도구 커스텀 등 관리

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@uniai-fe/next-providers",
+  "version": "0.1.1",
+  "description": "Next.js State Providers for UNIAI FE Projects",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "license": "MIT",
+  "homepage": "https://www.uniai.co.kr/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.22.0",
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=10"
+  },
+  "author": {
+    "name": "GraffitoRyu",
+    "email": "yth4135@naver.com",
+    "url": "https://github.com/GraffitoRyu"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "lint": "eslint . --max-warnings=0",
+    "typecheck": "tsc --project tsconfig.build.json --noEmit",
+    "build": "pnpm typecheck",
+    "dev": "tsc --project tsconfig.build.json --watch --noEmit",
+    "module:lint": "pnpm lint",
+    "module:typecheck": "pnpm typecheck",
+    "module:build": "pnpm build",
+    "next-providers:build": "pnpm run build",
+    "next-providers:dev": "pnpm run dev"
+  },
+  "main": "./src/index.tsx",
+  "module": "./src/index.tsx",
+  "exports": {
+    ".": "./src/index.tsx"
+  },
+  "peerDependencies": {
+    "next": ">= 15",
+    "react": ">= 19",
+    "react-dom": ">= 19",
+    "@tanstack/react-query": ">= 5",
+    "jotai": ">= 2",
+    "styled-components": ">= 6",
+    "airtable": ">= 0.12"
+  },
+  "peerDependenciesMeta": {
+    "optional": {
+      "@tanstack/react-query": true,
+      "jotai": true,
+      "styled-components": true
+    }
+  },
+  "devDependencies": {
+    "@uniai-fe/eslint-config": "workspace:*",
+    "@uniai-fe/tsconfig": "workspace:*",
+    "@uniai-fe/next-devkit": "workspace:*",
+    "@uniai-fe/util-functions": "workspace:*",
+    "@uniai-fe/util-jotai": "workspace:*",
+    "@uniai-fe/ui-legacy": "workspace:*",
+    "@uniai-fe/i18n": "workspace:*",
+    "@tanstack/react-query": "^5.90.8",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.4",
+    "@types/react-dom": "^19.2.3",
+    "airtable": "^0.12.2",
+    "eslint": "^9.39.1",
+    "jotai": "^2.15.1",
+    "jotai-tanstack-query": "^0.11.0",
+    "next": "^15.5.6",
+    "prettier": "^3.6.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "styled-components": "^6.1.19",
+    "typescript": "~5.9.3"
+  }
+}

package/src/NextRoots.tsx

@@ -0,0 +1,57 @@
+import { Suspense } from "react";
+import { Modal } from "@uniai-fe/ui-legacy";
+
+import StyledComponentsRegistry from "./lib/StyledComponentsRegistry";
+import AirtableProvider from "./provider/AirtableProvider";
+import { JotaiProvider } from "./provider/JotaiProvider";
+import { ReactQueryProvider } from "./provider/ReactQueryProvider";
+import RouterEventDetector from "./lib/RouterEventsDetector";
+import SetQueryCookie from "./lib/SetQueryCookie";
+import SystemThemeChecker from "./lib/SystemThemeChecker";
+import type { SystemLanguageType } from "@uniai-fe/next-devkit/types";
+
+/**
+ * Next.js Root Layout에 적용할 Provider 및 유틸리티 도구 집합
+ * @component
+ * @param {object} props
+ * @param {SystemLanguageType} [props.locale] 언어설정; "ko", "en"
+ * @param {object} [props.systemThemeOptions] 시스템 테마 체크 옵션
+ * @param {string[]} [props.systemThemeOptions.exceptPaths] 테마 체크 제외 경로
+ * @param {React.ReactNode} props.children
+ * @desc
+ * - React Query
+ * - Jotai
+ * - Apollo GraphQL
+ * - Airtable
+ * - Modal / Draggable Modal
+ * - System Theme Checker
+ * - Router Event Detector
+ */
+export default function NextRoots({
+  locale = "ko",
+  systemThemeOptions,
+  children,
+}: {
+  locale?: SystemLanguageType;
+  systemThemeOptions?: { exceptPaths: string[] };
+  children: React.ReactNode;
+}) {
+  return (
+    <ReactQueryProvider>
+      <JotaiProvider>
+        <SetQueryCookie />
+        <StyledComponentsRegistry>
+          <AirtableProvider locale={locale}>
+            {children}
+            <Modal.Basic.Provider />
+            <Modal.Draggable.Provider />
+          </AirtableProvider>
+          <SystemThemeChecker exceptPaths={systemThemeOptions?.exceptPaths} />
+          <Suspense fallback={null}>
+            <RouterEventDetector />
+          </Suspense>
+        </StyledComponentsRegistry>
+      </JotaiProvider>
+    </ReactQueryProvider>
+  );
+}

package/src/index.tsx

@@ -0,0 +1,3 @@
+import NextRoots from "./NextRoots";
+
+export { NextRoots };

package/src/lib/RouterEventsDetector.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useEffect } from "react";
+import { useSetAtom } from "jotai";
+
+import { modalState, modalDraggableState } from "@uniai-fe/ui-legacy";
+
+/**
+ * 경로변경 이벤트 감지
+ * @component
+ * @desc
+ * - 최상위 layout에서, 경로 변경을 감지
+ */
+export default function RouterEventDetector() {
+  const resetModalStack = useSetAtom(modalState);
+  const resetDraggableModalStack = useSetAtom(modalDraggableState);
+
+  const pathname = usePathname();
+
+  // 경로 변경 감지
+  useEffect(() => {
+    // 모달 스택 초기화
+    resetModalStack([]);
+    // 드래거블 모달 스택 초기화
+    resetDraggableModalStack([]);
+  }, [pathname, resetDraggableModalStack, resetModalStack]);
+
+  return null;
+}

package/src/lib/SetQueryCookie.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { useCallback, useEffect } from "react";
+import { setServerState } from "@uniai-fe/util-jotai";
+
+/**
+ * 쿠키 요청값 업데이트
+ * @component
+ * @desc
+ * - 클라이언트에서 정보를 받아 서버 쿠키로 요청이 필요한 경우 사용
+ */
+export default function SetQueryCookie() {
+  /**
+   * 언어설정 쿠키 요청값 업데이트
+   */
+  const setLocaleCookie = useCallback(async () => {
+    if (typeof window === "undefined") return;
+    const locale = localStorage.getItem("systemLocale");
+    await setServerState("systemLocale", locale, "ko");
+  }, []);
+
+  // 클라이언트에서 실행
+  useEffect(() => {
+    setLocaleCookie();
+  }, [setLocaleCookie]);
+
+  return null;
+}

package/src/lib/StyledComponentsRegistry.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import { useState } from "react";
+import { useServerInsertedHTML } from "next/navigation";
+import { ServerStyleSheet, StyleSheetManager } from "styled-components";
+
+/**
+ * styled-components의 SSR 활용을 위한 레지스트리 구성요소
+ * @component
+ * @desc
+ * - 최상위 layout에서 등록
+ */
+export default function StyledComponentsRegistry({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  // Only create stylesheet once with lazy initial state
+  // x-ref: https://reactjs.org/docs/hooks-reference.html#lazy-initial-state
+  const [styledComponentsStyleSheet] = useState(() => new ServerStyleSheet());
+
+  useServerInsertedHTML(() => {
+    const styles = styledComponentsStyleSheet.getStyleElement();
+    styledComponentsStyleSheet.instance.clearTag();
+    return <>{styles}</>;
+  });
+
+  if (typeof window !== "undefined") return <>{children}</>;
+
+  return (
+    <StyleSheetManager sheet={styledComponentsStyleSheet.instance}>
+      {children}
+    </StyleSheetManager>
+  );
+}

package/src/lib/SystemThemeChecker.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useEffect } from "react";
+import { useAtomValue } from "jotai";
+import { systemThemeState } from "@uniai-fe/util-jotai";
+
+/**
+ * 서비스 테마관리 공급자
+ * @component
+ * @desc
+ * - 최상위 layout에서 관리
+ */
+export default function SystemThemeChecker({
+  serviceType = "farm",
+  exceptPaths = [],
+}: {
+  serviceType?: string;
+  exceptPaths?: string[];
+}) {
+  const systemTheme = useAtomValue(systemThemeState);
+  const pathname = usePathname();
+
+  // const locale = useLocale();
+
+  useEffect(() => {
+    if (!systemTheme[serviceType] || exceptPaths.includes(pathname)) {
+      document.documentElement.classList.remove(`dark-mode`);
+      return;
+    }
+    document.documentElement.classList.remove(`dark-mode`);
+    if (systemTheme[serviceType] === "dark")
+      document.documentElement.classList.add(
+        `${systemTheme[serviceType]}-mode`,
+      );
+  }, [exceptPaths, pathname, serviceType, systemTheme]);
+
+  return null;
+}

package/src/provider/AirtableProvider.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+import {
+  dehydrate,
+  HydrationBoundary,
+  QueryClient,
+} from "@tanstack/react-query";
+import { getAirtableData } from "@uniai-fe/i18n/api";
+import type { SystemLanguageType } from "@uniai-fe/next-devkit/types";
+
+/**
+ * 다국어 지원을 위한 Airtable 데이터 호출 공급자
+ * @component
+ * @property {SystemLanguageType} locale "ko", "en", "jp", string
+ * @property {React.ReactNode} children
+ * @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
+ * @desc
+ * - 데이터를 서버에서 미리 불러오기 위해, 서버 컴포넌트로 구성
+ */
+export default async function AirtableProvider({
+  locale: serverLocale,
+  children,
+}: {
+  locale: SystemLanguageType;
+  children: React.ReactNode;
+}) {
+  // 서버는 항상 새로운 client를 선언해야 함
+  const serverQueryClient = new QueryClient();
+
+  // 데이터 호출
+  await serverQueryClient.prefetchQuery({
+    queryKey: ["airtable", serverLocale],
+    queryFn: () => getAirtableData(serverLocale),
+  });
+
+  return (
+    <HydrationBoundary state={dehydrate(serverQueryClient)}>
+      {children}
+    </HydrationBoundary>
+  );
+}

package/src/provider/JotaiProvider.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { Provider } from "jotai";
+import { useHydrateAtoms } from "jotai/react/utils";
+import { queryClientAtom } from "jotai-tanstack-query";
+import { getQueryClient } from "./ReactQueryProvider";
+
+export function JotaiHydrateAtoms({ children }: { children: React.ReactNode }) {
+  useHydrateAtoms([[queryClientAtom, getQueryClient()]]);
+  return children;
+}
+
+/**
+ * Jotai 상태 공급자
+ * @component
+ */
+export function JotaiProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <Provider>
+      <JotaiHydrateAtoms>{children}</JotaiHydrateAtoms>
+    </Provider>
+  );
+}

package/src/provider/ReactQueryProvider.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import {
+  defaultShouldDehydrateQuery,
+  isServer,
+  QueryClient,
+  QueryClientProvider,
+} from "@tanstack/react-query";
+
+/**
+ * 클라이언트 단에서의 React Query client
+ * @type {QueryClient | undefined}
+ */
+let browserQueryClient: QueryClient | undefined = undefined;
+
+/**
+ * React Query client 생성
+ * - 서비스 전역에 적용할 쿼리옵션을 사전에 지정하여 생성
+ * @return {QueryClient}
+ */
+function makeQueryClient(): QueryClient {
+  return new QueryClient({
+    // react-query 전역 설정
+    defaultOptions: {
+      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",
+      },
+    },
+  });
+}
+
+/**
+ * React Query client 생성
+ * @return {QueryClient}
+ */
+export function getQueryClient(): QueryClient {
+  if (isServer) {
+    // Server: always make a new query client
+    return makeQueryClient();
+  } 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();
+    return browserQueryClient;
+  }
+}
+
+/**
+ * ReactQuery 상태 공급자
+ * @component
+ * @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;
+}) {
+  // 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();
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}