sh-ui-cli 0.59.9 → 0.61.1

package/templates/nextjs-app/_arch/fsd/src/shared/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/fsd/src/shared/ui/PrefetchBoundary/index.tsx

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

package/templates/nextjs-app/vitest.config.ts

@@ -5,6 +5,10 @@ export default defineConfig({
   resolve: {
     alias: {
       '@': path.resolve(__dirname, '.'),
+      '@workspace/ui-app-name': path.resolve(
+        __dirname,
+        '../../packages/ui/ui-apps/ui-app-name/src',
+      ),
     },
   },
   test: {

package/templates/nextjs-standalone/.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-standalone/_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-standalone/_arch/flat/app/layout.tsx

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

package/templates/nextjs-standalone/_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-standalone/_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-standalone/_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-standalone/_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-standalone/_arch/flat/eslint.config.js

@@ -0,0 +1,123 @@
+import js from "@eslint/js"
+import pluginNext from "@next/eslint-plugin-next"
+import eslintConfigPrettier from "eslint-config-prettier"
+import boundaries from "eslint-plugin-boundaries"
+import checkFile from "eslint-plugin-check-file"
+import onlyWarn from "eslint-plugin-only-warn"
+import pluginReact from "eslint-plugin-react"
+import pluginReactHooks from "eslint-plugin-react-hooks"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+export default [
+  {
+    ignores: [".next/**", "dist/**", "node_modules/**"],
+  },
+
+  // ── Base ──
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  {
+    plugins: { onlyWarn },
+  },
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+    },
+  },
+
+  // ── React + Next.js ──
+  {
+    ...pluginReact.configs.flat.recommended,
+    languageOptions: {
+      ...pluginReact.configs.flat.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+      },
+    },
+  },
+  {
+    plugins: {
+      "@next/next": pluginNext,
+    },
+    rules: {
+      ...pluginNext.configs.recommended.rules,
+      ...pluginNext.configs["core-web-vitals"].rules,
+    },
+  },
+  {
+    plugins: {
+      "react-hooks": pluginReactHooks,
+    },
+    settings: { react: { version: "detect" } },
+    rules: {
+      ...pluginReactHooks.configs.recommended.rules,
+      "react/react-in-jsx-scope": "off",
+      "react/prop-types": "off",
+      "react/function-component-definition": [
+        "warn",
+        {
+          namedComponents: "function-declaration",
+          unnamedComponents: "arrow-function",
+        },
+      ],
+    },
+  },
+
+  // ── Flat-arch boundaries ──
+  // FSD 의 src/* 슬라이스 대신 flat 의 lib/components/app 의존 방향만 강제.
+  {
+    plugins: { boundaries },
+    settings: {
+      "boundaries/elements": [
+        { type: "lib", pattern: ["lib/*"], mode: "folder" },
+        { type: "components", pattern: ["components/*"], mode: "folder" },
+        { type: "app", pattern: ["app"], mode: "folder" },
+      ],
+      "boundaries/ignore": ["**/*.test.*", "**/*.spec.*"],
+    },
+    rules: {
+      "boundaries/element-types": [
+        "warn",
+        {
+          default: "disallow",
+          rules: [
+            { from: "app", allow: ["components", "lib"] },
+            { from: "components", allow: ["components", "lib"] },
+            { from: "lib", allow: ["lib"] },
+          ],
+        },
+      ],
+    },
+  },
+
+  // ── File naming ──
+  {
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        {
+          "**/components/**/*.tsx": "PASCAL_CASE",
+          "**/lib/**/*.ts": "CAMEL_CASE",
+        },
+        { ignoreMiddleExtensions: true },
+      ],
+    },
+  },
+  {
+    files: [
+      "**/index.tsx", "**/index.ts",
+      "**/layout.tsx", "**/page.tsx",
+      "**/error.tsx", "**/not-found.tsx",
+      "**/routing.ts", "**/navigation.ts", "**/request.ts",
+    ],
+    rules: {
+      "check-file/filename-naming-convention": "off",
+    },
+  },
+]

package/templates/nextjs-standalone/_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-standalone/_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-standalone/_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-standalone/_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-standalone/_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-standalone/_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-standalone/_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-standalone/_arch/flat/tsconfig.json

@@ -21,8 +21,7 @@
     "baseUrl": ".",
     "paths": {
       "@/lib/*": ["./lib/*"],
-      "@/components/*": ["./components/*"],
-      "@/app/*": ["./app/*"]
+      "@/components/*": ["./components/*"]
     },
     "plugins": [
       {

package/templates/nextjs-standalone/_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-standalone/_arch/fsd/app/layout.tsx

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

package/templates/nextjs-standalone/_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-standalone/_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-standalone/_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-standalone/_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-standalone/_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;
+}