sh-ui-cli 0.59.9 → 0.61.1

package/templates/monorepo/packages/typescript-config/package.json

@@ -1,5 +1,10 @@
 {
   "name": "@workspace/typescript-config",
   "version": "0.0.0",
-  "private": true
+  "private": true,
+  "exports": {
+    "./base.json": "./base.json",
+    "./nextjs.json": "./nextjs.json",
+    "./react-library.json": "./react-library.json"
+  }
 }

package/templates/monorepo/packages/ui/ui-core/tsconfig.json

@@ -6,6 +6,6 @@
       "@workspace/ui-core/*": ["./src/*"]
     }
   },
-  "include": ["."],
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
   "exclude": ["node_modules", "dist"]
 }

package/templates/monorepo/pnpm-workspace.yaml

@@ -1,5 +1,6 @@
 packages:
   - "apps/*"
-  - "packages/*"
+  - "packages/eslint-config"
+  - "packages/typescript-config"
   - "packages/ui/ui-core"
   - "packages/ui/ui-apps/*"

package/templates/nextjs-app/.env.example

@@ -1,2 +1,3 @@
-# API
-API_URL=http://localhost:8080
+# API — serverFetch 가 prefix 없이 그대로 fetch.
+# 백엔드의 base path 까지 포함해서 적어 주세요. 예: http://localhost:8080/api
+API_URL=http://localhost:8080/api

package/templates/nextjs-app/README.md

@@ -9,22 +9,23 @@ UI 컴포넌트는 `@workspace/ui-{name}` 패키지를 참조하며, sh-ui 설
 - **React 19**
 - **TypeScript 5.9**
 - **@workspace/ui-{name}** (sh-ui 컴포넌트 패키지)
-- **TanStack React Query** + **Axios**
-- **Zustand**
+- **TanStack React Query** (server state, isomorphic fetch — Axios 미사용)
+- **Zustand** (client state)
 - **next-themes** + **Sonner**
 - **Zod**
 - **Vitest** + **Testing Library**
-- **Docker** 지원
 
 ## 프로젝트 구조
 
 ```
 ├── app/                      # Next.js App Router
 │   ├── layout.tsx            # 루트 레이아웃 (@workspace/ui-{name}/globals.css import)
-│   └── page.tsx
-├── src/
+│   │                         #   next-intl 활성 시 app/[locale]/layout.tsx 로 이동
+│   └── page.tsx              # next-intl 활성 시 app/[locale]/page.tsx 로 이동
+├── src/                      # FSD 아키텍처 — flat 선택 시 `lib/` + `components/` 로 분기
 │   ├── app/
-│   │   └── providers/        # QueryClient, Theme, Toaster
+│   │   ├── providers/        # QueryClient, Theme, Toaster (Sentry 시 FallbackBoundary)
+│   │   └── layouts/          # RootLayout (html/body)
 │   ├── shared/               # FSD: 공유 유틸, 설정, 타입
 │   ├── entities/
 │   ├── features/
@@ -35,7 +36,6 @@ UI 컴포넌트는 `@workspace/ui-{name}` 패키지를 참조하며, sh-ui 설
 ├── postcss.config.mjs        # @workspace/ui-{name}/postcss.config 재사용
 ├── next.config.ts
 ├── vitest.config.ts
-├── Dockerfile
 └── .env.example
 ```
 
@@ -55,10 +55,10 @@ apps/{name}/
 
 ```bash
 # 모든 ui 패키지에 추가 (대화형)
-npx sh-ui-create add-component button
+npx sh-ui-cli create add-component button
 
 # 이 앱의 ui 패키지에만 추가
-npx sh-ui-create add-component button --app {name}
+npx sh-ui-cli create add-component button --app {name}
 ```
 
 각 `ui-{app}/` 패키지의 `sh-ui.config.json` 경로 설정에 따라 `src/components/` 로 복사됨.

package/templates/nextjs-app/_arch/flat/app/api/proxy/[...path]/route.ts

@@ -56,7 +56,7 @@ const proxyRequest = async (
         data: null,
         error: {
           code: 'NETWORK_ERROR',
-          message: '서버에 연결할 수 없습니다.',
+          message: 'Failed to reach upstream server.',
         },
       },
       { status: 502 },

package/templates/nextjs-app/_arch/flat/app/layout.tsx

@@ -3,8 +3,8 @@ import '@workspace/ui-app-name/globals.css';
 import { RootLayout } from '@/components/layouts/RootLayout';
 
 export const metadata: Metadata = {
-  title: 'App Name',
-  description: 'App Description',
+  title: 'sh-ui app',
+  description: 'sh-ui 기반 앱 — metadata 를 변경하세요.',
 };
 
 export default function Layout({

package/templates/nextjs-app/_arch/flat/components/common/PrefetchBoundary/index.tsx

@@ -6,7 +6,7 @@ import {
   HydrationBoundary,
 } from '@tanstack/react-query';
 
-import getQueryClient from '@/lib/utils/getQueryClient';
+import { getQueryClient } from '@/lib/utils/getQueryClient';
 
 export type FetchOptions = Pick<FetchQueryOptions, 'queryKey' | 'queryFn'>;
 

package/templates/nextjs-app/_arch/flat/components/layouts/RootLayout.tsx

@@ -1,6 +1,8 @@
 import { GlobalProvider } from '@/components/providers';
 
 export function RootLayout({ children }: { children: React.ReactNode }) {
+  // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
+  // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
   return (
     <html lang='ko' suppressHydrationWarning>
       <body>

package/templates/nextjs-app/_arch/flat/components/providers/GlobalProvider/index.tsx

@@ -3,7 +3,7 @@ import { Toaster } from 'sonner';
 
 import { QueryClientProvider } from '../tanstack/QueryClientProvider';
 import { TanstackDevtoolsProvider } from '../tanstack/TanstackDevtoolsProvider';
-import { ThemeProviders } from '../theme/ThemeProviders';
+import { ThemeProvider } from '../theme/ThemeProvider';
 
 interface GlobalProviderProps {
   children: ReactNode;
@@ -11,13 +11,13 @@ interface GlobalProviderProps {
 
 export function GlobalProvider({ children }: GlobalProviderProps) {
   return (
-    <ThemeProviders>
+    <ThemeProvider>
       <QueryClientProvider>
         <TanstackDevtoolsProvider>
           <Toaster />
           {children}
         </TanstackDevtoolsProvider>
       </QueryClientProvider>
-    </ThemeProviders>
+    </ThemeProvider>
   );
 }

package/templates/nextjs-app/_arch/flat/components/providers/theme/ThemeProvider.tsx

@@ -0,0 +1,12 @@
+'use client';
+
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+import type { ReactNode } from 'react';
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  return (
+    <NextThemesProvider attribute='class' defaultTheme='system' enableSystem>
+      {children}
+    </NextThemesProvider>
+  );
+}

package/templates/nextjs-app/_arch/flat/eslint.config.js

@@ -0,0 +1,10 @@
+import { nextJsConfig } from "@workspace/eslint-config/next-js"
+import { flatConfig } from "@workspace/eslint-config/flat"
+
+export default [
+  {
+    ignores: [".next/**", "dist/**", "node_modules/**"],
+  },
+  ...nextJsConfig,
+  ...flatConfig,
+]

package/templates/nextjs-app/_arch/flat/lib/api/clientFetch.ts

@@ -23,10 +23,10 @@ export async function clientFetch<T>(
   const body = (await res.json()) as ApiResponse<T>;
 
   if (res.status === 401) {
-    if (
-      typeof window !== 'undefined' &&
-      !window.location.pathname.startsWith('/sign-in')
-    ) {
+    // 이미 sign-in 페이지면 redirect 루프 방지.
+    // next-intl 활성 시 path 가 `/ko/sign-in` 형태가 되므로 regex 로 match.
+    if (typeof window !== 'undefined' && !/\/sign-in(\/|$)/.test(window.location.pathname)) {
+      // /sign-in 으로만 보내면 middleware (next-intl 활성 시) 가 default locale 을 prefix 추가.
       window.location.href = '/sign-in';
     }
     throw new ApiError(401, body.error?.code ?? 'UNAUTHORIZED', body.error);

package/templates/nextjs-app/_arch/flat/lib/api/errorMessages.ts

@@ -0,0 +1,37 @@
+import { ApiError } from './error';
+
+/**
+ * 에러 코드 → 사용자 facing 메시지 mapping.
+ *
+ * 백엔드가 보내는 raw `error.message` 를 그대로 toast 로 띄우면 i18n 어긋나거나
+ * 내부 노출이 될 수 있어, frontend 가 정의한 안전한 메시지로 변환하는 게 권장.
+ * 코드별로 명시 안 된 경우 `error.data.message` (backend 메시지) → fallback.
+ *
+ * 사용자 프로젝트에서 자유롭게 추가/수정. next-intl 활성 시엔 `useTranslations`
+ * 와 결합해 hook 형태로 변환 가능 (이 파일은 RSC/CSR 양쪽 호환을 위해 module).
+ */
+export const ERROR_MESSAGES: Record<string, string> = {
+  UNAUTHORIZED: '로그인이 필요합니다.',
+  FORBIDDEN: '접근 권한이 없습니다.',
+  NOT_FOUND: '요청한 리소스를 찾을 수 없습니다.',
+  NETWORK_ERROR: '서버에 연결할 수 없습니다. 잠시 후 다시 시도해 주세요.',
+  // 사용자 정의 코드를 여기에 추가하세요.
+};
+
+const DEFAULT_FALLBACK = '일시적인 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.';
+
+/**
+ * 에러 → 사용자 facing 메시지 결정.
+ *  1. ApiError + 코드가 ERROR_MESSAGES 에 있으면 그 메시지
+ *  2. ApiError 의 backend `data.message` (있으면)
+ *  3. 호출자의 fallback
+ *  4. 글로벌 DEFAULT_FALLBACK
+ */
+export function resolveErrorMessage(error: unknown, fallback?: string): string {
+  if (error instanceof ApiError) {
+    const mapped = ERROR_MESSAGES[error.code];
+    if (mapped) return mapped;
+    if (error.data?.message) return error.data.message;
+  }
+  return fallback ?? DEFAULT_FALLBACK;
+}

package/templates/nextjs-app/_arch/flat/lib/hooks/useAppMutation.ts

@@ -5,7 +5,8 @@ import {
 } from '@tanstack/react-query';
 import { toast } from 'sonner';
 
-import { ApiError } from '../api/error';
+import { ApiError } from '@/lib/api/error';
+import { resolveErrorMessage } from '@/lib/api/errorMessages';
 
 type AppMutationOptions<
   TData = unknown,
@@ -13,13 +14,19 @@ type AppMutationOptions<
   TVariables = void,
   TContext = unknown,
 > = UseMutationOptions<TData, TError, TVariables, TContext> & {
+  /** ApiError 가 아니거나 mapping 에 없을 때의 fallback 메시지. */
   errorMessage?: string;
+  /** false 면 toast 띄우지 않음. */
   showErrorToast?: boolean;
 };
 
 /**
- * useMutation 래퍼 — 에러 발생 시 ApiError.message 를 toast 로 띄운다.
- * showErrorToast: false 로 끌 수 있고, errorMessage 로 fallback 메시지 지정.
+ * useMutation 래퍼 — 에러 발생 시 `resolveErrorMessage` 를 통해 안전한
+ * 사용자 facing 메시지를 toast 로 띄운다. backend 가 보낸 raw 메시지를 그대로
+ * 띄우지 않고 `errorMessages.ts` 의 mapping 을 우선 사용해 일관된 사용자
+ * 경험과 i18n 친화성을 확보.
+ *
+ * showErrorToast: false 로 자동 toast 끌 수 있고, errorMessage 로 fallback 지정.
  */
 export const useAppMutation = <
   TData = unknown,
@@ -39,10 +46,7 @@ export const useAppMutation = <
       if (!showErrorToast) return;
 
       const [error] = args;
-      const message =
-        error instanceof ApiError
-          ? (error.data?.message ?? errorMessage)
-          : errorMessage;
+      const message = resolveErrorMessage(error, errorMessage);
 
       if (message) {
         toast.error(message);
@@ -50,3 +54,6 @@ export const useAppMutation = <
     },
   });
 };
+
+// re-export ApiError 타입을 쓰는 사용처 편의용 (선택).
+export type { ApiError };

package/templates/nextjs-app/_arch/flat/lib/test/renderWithProviders.tsx

@@ -1,4 +1,4 @@
-import type { ReactElement, ReactNode } from 'react';
+import type { ComponentType, ReactElement, ReactNode } from 'react';
 
 import {
   render,
@@ -7,11 +7,17 @@ import {
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ThemeProvider } from 'next-themes';
 
 import { createTestQueryClient } from './createTestQueryClient';
 
 type Options = Omit<RenderOptions, 'wrapper'> & {
   queryClient?: QueryClient;
+  /**
+   * 외부 Provider 가 필요할 때 (예: next-intl 활성 프로젝트에서
+   * `NextIntlClientProvider`) 사용. ThemeProvider 안쪽 / QueryClientProvider 바깥에 wrap.
+   */
+  extraWrapper?: ComponentType<{ children: ReactNode }>;
 };
 
 type Result = RenderResult & {
@@ -20,18 +26,37 @@ type Result = RenderResult & {
 };
 
 /**
- * RTL render + QueryClientProvider + userEvent setup 한 번에.
- * 추가 Provider 가 필요하면 이 파일을 직접 수정하거나 wrapper 옵션을 쓴다.
+ * RTL render + ThemeProvider + QueryClientProvider + userEvent setup 한 번에.
+ *
+ * next-intl 프로젝트에서 `useTranslations` 사용 컴포넌트 테스트 시:
+ *
+ *   const Intl = ({ children }) => (
+ *     <NextIntlClientProvider locale='ko' messages={ko}>
+ *       {children}
+ *     </NextIntlClientProvider>
+ *   );
+ *   renderWithProviders(<MyComponent />, { extraWrapper: Intl });
  */
 export const renderWithProviders = (
   ui: ReactElement,
   options: Options = {},
 ): Result => {
-  const { queryClient = createTestQueryClient(), ...rtlOptions } = options;
+  const {
+    queryClient = createTestQueryClient(),
+    extraWrapper: Extra,
+    ...rtlOptions
+  } = options;
 
-  const Wrapper = ({ children }: { children: ReactNode }) => (
-    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
-  );
+  const Wrapper = ({ children }: { children: ReactNode }) => {
+    const inner = (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+    return (
+      <ThemeProvider attribute='class' defaultTheme='light' enableSystem={false}>
+        {Extra ? <Extra>{inner}</Extra> : inner}
+      </ThemeProvider>
+    );
+  };
 
   const result = render(ui, { wrapper: Wrapper, ...rtlOptions });
   const user = userEvent.setup();

package/templates/nextjs-app/_arch/flat/lib/utils/formatDate.ts

@@ -1,5 +1,9 @@
 /**
  * Date → 로케일 기반 날짜 포맷 (시간 없음).
+ *
+ * 비-i18n 프로젝트면 default 'ko-KR' 사용. next-intl 활성 시엔 이 util 을 직접
+ * 부르지 말고 같은 모듈의 hook (`useFormatDate`) 을 사용하세요 — 현재 locale 을
+ * 자동으로 따릅니다 (next-intl 플러그인이 emit).
  */
 export const formatDate = (date: Date, locale = 'ko-KR'): string =>
   new Intl.DateTimeFormat(locale, {

package/templates/nextjs-app/_arch/flat/lib/utils/formatPrice.ts

@@ -1,10 +1,18 @@
 /**
- * 숫자 → 한국 원화(KRW) 포맷. 소수점 없음.
- * 예: 12000 → "₩12,000"
+ * 숫자 → 통화 포맷. default ko-KR + KRW 이지만 두 인자 모두 override 가능.
+ * 예: formatPrice(12000)            → "₩12,000"
+ *     formatPrice(99.5, 'en-US', 'USD') → "$99.50"
+ *
+ * next-intl 활성 시엔 같은 모듈의 hook (`useFormatPrice`) 을 사용하면 현재
+ * locale 을 자동으로 따릅니다 (next-intl 플러그인이 emit).
  */
-export const formatPrice = (amount: number, locale = 'ko-KR'): string =>
+export const formatPrice = (
+  amount: number,
+  locale = 'ko-KR',
+  currency = 'KRW',
+): string =>
   new Intl.NumberFormat(locale, {
     style: 'currency',
-    currency: 'KRW',
-    maximumFractionDigits: 0,
+    currency,
+    maximumFractionDigits: currency === 'KRW' ? 0 : 2,
   }).format(amount);

package/templates/nextjs-app/_arch/flat/lib/utils/getQueryClient.ts

@@ -9,6 +9,6 @@ import {
  * RSC 와 클라이언트 양쪽에서 안전하게 호출 가능한 QueryClient 핸들.
  * 서버에서는 React `cache()` 로 요청 단위 싱글턴, 브라우저에서는 모듈 싱글턴.
  */
-export default function getQueryClient() {
+export function getQueryClient() {
   return isServer ? getServerQueryClient() : getBrowserQueryClient();
 }

package/templates/nextjs-app/_arch/flat/tsconfig.json

@@ -5,7 +5,6 @@
     "paths": {
       "@/lib/*": ["./lib/*"],
       "@/components/*": ["./components/*"],
-      "@/app/*": ["./app/*"],
       "@workspace/ui-app-name/*": ["../../packages/ui/ui-apps/ui-app-name/src/*"]
     },
     "plugins": [

package/templates/nextjs-app/_arch/fsd/app/api/proxy/[...path]/route.ts

@@ -56,7 +56,7 @@ const proxyRequest = async (
         data: null,
         error: {
           code: 'NETWORK_ERROR',
-          message: '서버에 연결할 수 없습니다.',
+          message: 'Failed to reach upstream server.',
         },
       },
       { status: 502 },

package/templates/nextjs-app/_arch/fsd/app/layout.tsx

@@ -3,8 +3,8 @@ import '@workspace/ui-app-name/globals.css';
 import { RootLayout } from '@/src/app/layouts/RootLayout';
 
 export const metadata: Metadata = {
-  title: 'App Name',
-  description: 'App Description',
+  title: 'sh-ui app',
+  description: 'sh-ui 기반 앱 — metadata 를 변경하세요.',
 };
 
 export default function Layout({

package/templates/nextjs-app/_arch/fsd/src/app/layouts/RootLayout.tsx

@@ -1,6 +1,8 @@
 import { GlobalProvider } from '@/src/app/providers';
 
 export function RootLayout({ children }: { children: React.ReactNode }) {
+  // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
+  // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
   return (
     <html lang='ko' suppressHydrationWarning>
       <body>

package/templates/nextjs-app/_arch/fsd/src/app/providers/GlobalProvider/index.tsx

@@ -3,7 +3,7 @@ import { Toaster } from 'sonner';
 
 import { QueryClientProvider } from '../tanstack/QueryClientProvider';
 import { TanstackDevtoolsProvider } from '../tanstack/TanstackDevtoolsProvider';
-import { ThemeProviders } from '../theme/ThemeProviders';
+import { ThemeProvider } from '../theme/ThemeProvider';
 
 interface GlobalProviderProps {
   children: ReactNode;
@@ -11,13 +11,13 @@ interface GlobalProviderProps {
 
 export function GlobalProvider({ children }: GlobalProviderProps) {
   return (
-    <ThemeProviders>
+    <ThemeProvider>
       <QueryClientProvider>
         <TanstackDevtoolsProvider>
           <Toaster />
           {children}
         </TanstackDevtoolsProvider>
       </QueryClientProvider>
-    </ThemeProviders>
+    </ThemeProvider>
   );
 }

package/templates/nextjs-app/_arch/fsd/src/app/providers/theme/ThemeProvider.tsx

@@ -0,0 +1,12 @@
+'use client';
+
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+import type { ReactNode } from 'react';
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  return (
+    <NextThemesProvider attribute='class' defaultTheme='system' enableSystem>
+      {children}
+    </NextThemesProvider>
+  );
+}

package/templates/nextjs-app/_arch/fsd/src/shared/api/clientFetch.ts

@@ -23,10 +23,10 @@ export async function clientFetch<T>(
   const body = (await res.json()) as ApiResponse<T>;
 
   if (res.status === 401) {
-    if (
-      typeof window !== 'undefined' &&
-      !window.location.pathname.startsWith('/sign-in')
-    ) {
+    // 이미 sign-in 페이지면 redirect 루프 방지.
+    // next-intl 활성 시 path 가 `/ko/sign-in` 형태가 되므로 regex 로 match.
+    if (typeof window !== 'undefined' && !/\/sign-in(\/|$)/.test(window.location.pathname)) {
+      // /sign-in 으로만 보내면 middleware (next-intl 활성 시) 가 default locale 을 prefix 추가.
       window.location.href = '/sign-in';
     }
     throw new ApiError(401, body.error?.code ?? 'UNAUTHORIZED', body.error);

package/templates/nextjs-app/_arch/fsd/src/shared/api/errorMessages.ts

@@ -0,0 +1,37 @@
+import { ApiError } from './error';
+
+/**
+ * 에러 코드 → 사용자 facing 메시지 mapping.
+ *
+ * 백엔드가 보내는 raw `error.message` 를 그대로 toast 로 띄우면 i18n 어긋나거나
+ * 내부 노출이 될 수 있어, frontend 가 정의한 안전한 메시지로 변환하는 게 권장.
+ * 코드별로 명시 안 된 경우 `error.data.message` (backend 메시지) → fallback.
+ *
+ * 사용자 프로젝트에서 자유롭게 추가/수정. next-intl 활성 시엔 `useTranslations`
+ * 와 결합해 hook 형태로 변환 가능 (이 파일은 RSC/CSR 양쪽 호환을 위해 module).
+ */
+export const ERROR_MESSAGES: Record<string, string> = {
+  UNAUTHORIZED: '로그인이 필요합니다.',
+  FORBIDDEN: '접근 권한이 없습니다.',
+  NOT_FOUND: '요청한 리소스를 찾을 수 없습니다.',
+  NETWORK_ERROR: '서버에 연결할 수 없습니다. 잠시 후 다시 시도해 주세요.',
+  // 사용자 정의 코드를 여기에 추가하세요.
+};
+
+const DEFAULT_FALLBACK = '일시적인 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.';
+
+/**
+ * 에러 → 사용자 facing 메시지 결정.
+ *  1. ApiError + 코드가 ERROR_MESSAGES 에 있으면 그 메시지
+ *  2. ApiError 의 backend `data.message` (있으면)
+ *  3. 호출자의 fallback
+ *  4. 글로벌 DEFAULT_FALLBACK
+ */
+export function resolveErrorMessage(error: unknown, fallback?: string): string {
+  if (error instanceof ApiError) {
+    const mapped = ERROR_MESSAGES[error.code];
+    if (mapped) return mapped;
+    if (error.data?.message) return error.data.message;
+  }
+  return fallback ?? DEFAULT_FALLBACK;
+}

package/templates/nextjs-app/_arch/fsd/src/shared/hooks/useAppMutation.ts

@@ -5,7 +5,8 @@ import {
 } from '@tanstack/react-query';
 import { toast } from 'sonner';
 
-import { ApiError } from '../api/error';
+import { ApiError } from '@/src/shared/api/error';
+import { resolveErrorMessage } from '@/src/shared/api/errorMessages';
 
 type AppMutationOptions<
   TData = unknown,
@@ -13,13 +14,19 @@ type AppMutationOptions<
   TVariables = void,
   TContext = unknown,
 > = UseMutationOptions<TData, TError, TVariables, TContext> & {
+  /** ApiError 가 아니거나 mapping 에 없을 때의 fallback 메시지. */
   errorMessage?: string;
+  /** false 면 toast 띄우지 않음. */
   showErrorToast?: boolean;
 };
 
 /**
- * useMutation 래퍼 — 에러 발생 시 ApiError.message 를 toast 로 띄운다.
- * showErrorToast: false 로 끌 수 있고, errorMessage 로 fallback 메시지 지정.
+ * useMutation 래퍼 — 에러 발생 시 `resolveErrorMessage` 를 통해 안전한
+ * 사용자 facing 메시지를 toast 로 띄운다. backend 가 보낸 raw 메시지를 그대로
+ * 띄우지 않고 `errorMessages.ts` 의 mapping 을 우선 사용해 일관된 사용자
+ * 경험과 i18n 친화성을 확보.
+ *
+ * showErrorToast: false 로 자동 toast 끌 수 있고, errorMessage 로 fallback 지정.
  */
 export const useAppMutation = <
   TData = unknown,
@@ -39,10 +46,7 @@ export const useAppMutation = <
       if (!showErrorToast) return;
 
       const [error] = args;
-      const message =
-        error instanceof ApiError
-          ? (error.data?.message ?? errorMessage)
-          : errorMessage;
+      const message = resolveErrorMessage(error, errorMessage);
 
       if (message) {
         toast.error(message);
@@ -50,3 +54,6 @@ export const useAppMutation = <
     },
   });
 };
+
+// re-export ApiError 타입을 쓰는 사용처 편의용 (선택).
+export type { ApiError };

package/templates/nextjs-app/_arch/fsd/src/shared/lib/formatDate.ts

@@ -1,5 +1,9 @@
 /**
  * Date → 로케일 기반 날짜 포맷 (시간 없음).
+ *
+ * 비-i18n 프로젝트면 default 'ko-KR' 사용. next-intl 활성 시엔 이 util 을 직접
+ * 부르지 말고 같은 모듈의 hook (`useFormatDate`) 을 사용하세요 — 현재 locale 을
+ * 자동으로 따릅니다 (next-intl 플러그인이 emit).
  */
 export const formatDate = (date: Date, locale = 'ko-KR'): string =>
   new Intl.DateTimeFormat(locale, {

package/templates/nextjs-app/_arch/fsd/src/shared/lib/formatPrice.ts

@@ -1,10 +1,18 @@
 /**
- * 숫자 → 한국 원화(KRW) 포맷. 소수점 없음.
- * 예: 12000 → "₩12,000"
+ * 숫자 → 통화 포맷. default ko-KR + KRW 이지만 두 인자 모두 override 가능.
+ * 예: formatPrice(12000)            → "₩12,000"
+ *     formatPrice(99.5, 'en-US', 'USD') → "$99.50"
+ *
+ * next-intl 활성 시엔 같은 모듈의 hook (`useFormatPrice`) 을 사용하면 현재
+ * locale 을 자동으로 따릅니다 (next-intl 플러그인이 emit).
  */
-export const formatPrice = (amount: number, locale = 'ko-KR'): string =>
+export const formatPrice = (
+  amount: number,
+  locale = 'ko-KR',
+  currency = 'KRW',
+): string =>
   new Intl.NumberFormat(locale, {
     style: 'currency',
-    currency: 'KRW',
-    maximumFractionDigits: 0,
+    currency,
+    maximumFractionDigits: currency === 'KRW' ? 0 : 2,
   }).format(amount);

package/templates/nextjs-app/_arch/fsd/src/shared/lib/getQueryClient.ts

@@ -9,6 +9,6 @@ import {
  * RSC 와 클라이언트 양쪽에서 안전하게 호출 가능한 QueryClient 핸들.
  * 서버에서는 React `cache()` 로 요청 단위 싱글턴, 브라우저에서는 모듈 싱글턴.
  */
-export default function getQueryClient() {
+export function getQueryClient() {
   return isServer ? getServerQueryClient() : getBrowserQueryClient();
 }