sh-ui-cli 0.32.1 → 0.34.0

package/data/changelog/versions.json

@@ -2,6 +2,35 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.34.0",
+      "date": "2026-04-29",
+      "title": "Next 템플릿 — RSC prefetch / 에러 바운더리 / 테스트 헬퍼 + KRW·날짜 포맷 유틸 기본 탑재",
+      "type": "minor",
+      "highlights": [
+        "shared/ui/PrefetchBoundary + shared/lib/getQueryClient — RSC 에서 prefetch 후 dehydrate → 클라이언트 hydrate. 단일/배열 fetchOptions 모두 지원, 이미 깔린 TanStack Query 인프라와 즉시 호환",
+        "shared/ui/FallbackBoundary — Suspense + ErrorBoundary 합성, QueryErrorResetBoundary 와 연동돼 errorFallback 의 resetErrorBoundary 가 쿼리까지 함께 리셋. onError 콜백으로 외부 옵저버빌리티 (Sentry 등) 훅인 자유",
+        "shared/test/renderWithProviders + createTestQueryClient — RTL render + QueryClientProvider + userEvent 한 번에. 기존 vitest 인프라에 컴포넌트 테스트 진입장벽 제거",
+        "shared/lib/formatDate / formatPrice — 로케일 기반 Intl 포맷 유틸. formatPrice 는 한국 원화(KRW, 소수점 없음) 기본",
+        "@testing-library/react + user-event devDeps 추가 (양쪽 nextjs 템플릿)"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.34.0"
+    },
+    {
+      "version": "0.33.0",
+      "date": "2026-04-29",
+      "title": "중앙관리형 SSOT — sh-ui-cli/api 노출 + 플러그인 스키마 + --dry-run + CI 스캐폴드 게이트",
+      "type": "minor",
+      "highlights": [
+        "신규 public API — `import { allPlugins, CREATE_PLATFORMS, ... } from 'sh-ui-cli/api'`. 다른 워크스페이스 (apps/docs 등) 가 플러그인 메타와 enum 을 동기화 없이 사용. CreateProjectDialog / 사이드바 / 플러그인 허브 가 모두 derive 하도록 변경 — 새 플러그인 추가 시 plugins/ 폴더 한 군데만 건드리면 됨",
+        "신규 --dry-run 플래그 — 실제 파일 쓰지 않고 스캐폴드 결과 파일 목록만 출력. 디버깅 + CI 검증 보조. tmpdir 에 생성 후 즉시 정리해 사용자 cwd 무영향",
+        "플러그인 manifest zod 스키마 검증 — 모듈 로드 시점에 모든 플러그인 형태 체크. 'src/proxy.ts' 같은 잘못된 경로는 빌드 타임 거부 (v0.32.0 에서 발생한 회귀 차단)",
+        "CI 스캐폴드 게이트 — publish 전에 5가지 플러그인 조합으로 실제 스캐폴드 → fresh install → tsc --noEmit 까지 돌리는 스모크 단계 추가. 사용자가 받게 될 결과물을 publish 직전에 검증",
+        "통합 테스트 7개 추가 — 각 플러그인 + 조합의 핵심 파일 위치 / 내용 / 합성 검증 (proxy.ts root 위치, 합성된 proxy.ts 의 intl + 인증 가드, observability 의 Sentry vs no-op, axios 부재 등)",
+        "내부 정리 — packages/cli/src/constants.js 신설로 PLATFORMS/STRUCTURES/THEME_* 단일화. cli-args / mcp / init / generator 도움말 모두 derive"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.33.0"
+    },
     {
       "version": "0.32.1",
       "date": "2026-04-29",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,12 @@
   "bin": {
     "sh-ui": "./bin/sh-ui.mjs"
   },
+  "exports": {
+    "./api": {
+      "types": "./src/api.d.ts",
+      "default": "./src/api.js"
+    }
+  },
   "scripts": {
     "bundle-data": "node scripts/copy-data.mjs",
     "test": "vitest run",

package/src/api.d.ts

@@ -0,0 +1,42 @@
+/**
+ * sh-ui-cli 외부 노출 API 의 타입 선언.
+ * apps/docs 등 TypeScript 사용자가 자동완성과 타입 안전을 받을 수 있게.
+ */
+
+export type CreatePlatform = 'next' | 'flutter';
+export type CreateStructure = 'standalone' | 'monorepo';
+export type InitPlatform = 'react' | 'flutter';
+export type ThemeBase = 'neutral' | 'zinc' | 'slate';
+export type ThemeRadius = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+export type ThemeMode = 'light-dark' | 'light' | 'dark';
+
+export const CREATE_PLATFORMS: readonly CreatePlatform[];
+export const CREATE_STRUCTURES: readonly CreateStructure[];
+export const INIT_PLATFORMS: readonly InitPlatform[];
+export const THEME_BASES: readonly ThemeBase[];
+export const THEME_RADII: readonly ThemeRadius[];
+export const THEME_MODES: readonly ThemeMode[];
+
+export const INIT_DEFAULTS: {
+  platform: InitPlatform;
+  base: ThemeBase;
+  radius: ThemeRadius;
+  mode: ThemeMode;
+};
+
+export type PluginManifest = {
+  name: string;
+  label: string;
+  description?: string;
+  priority: number;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  envVars?: string[];
+  turboEnvVars?: string[];
+  imports?: string[];
+  providerImports?: string[];
+  providerWrappers?: Array<{ open: string; close: string } | string>;
+  files?: Record<string, string>;
+};
+
+export const allPlugins: readonly PluginManifest[];

package/src/api.js

@@ -0,0 +1,21 @@
+/**
+ * sh-ui-cli 외부 노출 API.
+ *
+ * apps/docs 같은 다른 워크스페이스 패키지가 플러그인 메타데이터와 enum 을
+ * 동기화 없이 사용하도록. package.json 의 "exports": { "./api": "./src/api.js" }
+ * 로 노출되며, 사용자는 다음과 같이 import:
+ *
+ *   import { allPlugins, CREATE_PLATFORMS } from 'sh-ui-cli/api';
+ */
+
+export {
+  CREATE_PLATFORMS,
+  CREATE_STRUCTURES,
+  INIT_PLATFORMS,
+  THEME_BASES,
+  THEME_RADII,
+  THEME_MODES,
+  INIT_DEFAULTS,
+} from './constants.js';
+
+export { allPlugins } from './create/plugins/index.js';

package/src/constants.js

@@ -0,0 +1,31 @@
+/**
+ * sh-ui-cli 의 모든 enum / 상수 단일 진실.
+ *
+ * 다른 모듈 (cli-args, mcp, init, generator) 과 외부 패키지 (apps/docs) 는
+ * 이 파일을 import 해서 사용한다. 새 값 추가 시 여기만 고치면 된다.
+ */
+
+// ─── 프로젝트 생성 (sh-ui-cli create) ───
+
+export const CREATE_PLATFORMS = ['next', 'flutter'];
+
+export const CREATE_STRUCTURES = ['standalone', 'monorepo'];
+
+// ─── 초기화 (sh-ui-cli init) — sh-ui 컴포넌트 설정 ───
+
+export const INIT_PLATFORMS = ['react', 'flutter'];
+
+export const THEME_BASES = ['neutral', 'zinc', 'slate'];
+
+export const THEME_RADII = ['none', 'sm', 'md', 'lg', 'xl', 'full'];
+
+export const THEME_MODES = ['light-dark', 'light', 'dark'];
+
+// ─── 기본값 ───
+
+export const INIT_DEFAULTS = {
+  platform: 'react',
+  base: 'neutral',
+  radius: 'md',
+  mode: 'light-dark',
+};

package/src/create/cli-args.js

@@ -1,9 +1,12 @@
-const VALID_PLATFORMS = ['next', 'flutter'];
-const VALID_STRUCTURES = ['standalone', 'monorepo'];
-const VALID_PLUGINS = ['sentry', 'next-intl', 'auth-jwt'];
+import { CREATE_PLATFORMS, CREATE_STRUCTURES } from '../constants.js';
+import { allPlugins } from './plugins/index.js';
+
+const VALID_PLATFORMS = CREATE_PLATFORMS;
+const VALID_STRUCTURES = CREATE_STRUCTURES;
+const VALID_PLUGINS = allPlugins.map((p) => p.name);
 
 const VALUE_FLAGS = ['platform', 'structure', 'plugins', 'theme', 'app'];
-const BOOL_FLAGS = ['yes', 'help'];
+const BOOL_FLAGS = ['yes', 'help', 'dry-run'];
 
 const SUBCOMMANDS = ['add-app', 'add-component'];
 
@@ -29,7 +32,9 @@ export const parseArgs = (argv) => {
     }
     const name = arg.slice(2);
     if (BOOL_FLAGS.includes(name)) {
-      flags[name] = true;
+      // dry-run 은 dryRun 으로 캐멀 케이스
+      const key = name === 'dry-run' ? 'dryRun' : name;
+      flags[key] = true;
       continue;
     }
     if (!VALUE_FLAGS.includes(name)) {
@@ -44,7 +49,9 @@ export const parseArgs = (argv) => {
       const list = value === '' ? [] : value.split(',').map((s) => s.trim()).filter(Boolean);
       for (const p of list) {
         if (!VALID_PLUGINS.includes(p)) {
-          throw new Error(`알 수 없는 플러그인: ${p}`);
+          throw new Error(
+            `알 수 없는 플러그인: ${p} (지원: ${VALID_PLUGINS.join(', ')})`,
+          );
         }
       }
       flags.plugins = list;

package/src/create/generator.js

@@ -1,6 +1,7 @@
 import { input, select, checkbox, confirm } from '@inquirer/prompts';
 import { execSync } from 'node:child_process';
 import fs from 'fs-extra';
+import os from 'node:os';
 import path from 'node:path';
 import { getPluginChoices, getPluginsByNames } from './plugins/index.js';
 import { decodeTheme } from './theme/decode.js';
@@ -53,9 +54,13 @@ export async function createProject(options = {}) {
 
   const theme = options.theme ? decodeTheme(options.theme) : null;
 
-  const targetDir = path.resolve(process.cwd(), projectName);
+  // dry-run 은 tmpdir 에 그대로 생성한 뒤 파일 목록 출력 + 정리.
+  // 사용자 cwd 를 건드리지 않으면서 실제 generation 흐름을 그대로 검증한다.
+  const targetDir = options.dryRun
+    ? await fs.mkdtemp(path.join(os.tmpdir(), 'sh-ui-dry-'))
+    : path.resolve(process.cwd(), projectName);
 
-  if (await fs.pathExists(targetDir)) {
+  if (!options.dryRun && await fs.pathExists(targetDir)) {
     if (options.yes) {
       await fs.remove(targetDir);
     } else {
@@ -102,12 +107,44 @@ export async function createProject(options = {}) {
     await generateMonorepo(targetDir, projectName, plugins, { yes: options.yes, theme });
   }
 
+  if (options.dryRun) {
+    const files = await listAllFiles(targetDir);
+    console.log(`\n[DRY RUN] ${projectName} 스캐폴드 시 작성될 파일 (${files.length}개):\n`);
+    for (const f of files.sort()) {
+      console.log(`  ${f}`);
+    }
+    await fs.remove(targetDir);
+    console.log(`\n실제 스캐폴드: --dry-run 제거 후 같은 명령 실행.`);
+    return;
+  }
+
   console.log(`\n✅ ${projectName} 프로젝트가 생성되었습니다!`);
   console.log(`\n  cd ${projectName}`);
   console.log('  pnpm install');
   console.log('  pnpm dev\n');
 }
 
+/**
+ * targetDir 아래 모든 파일을 상대 경로로 나열. node_modules 등은 자동 스킵
+ * (스캐폴드 직후라 install 안 한 상태기 때문).
+ */
+async function listAllFiles(targetDir) {
+  const collected = [];
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        collected.push(path.relative(targetDir, full));
+      }
+    }
+  }
+  await walk(targetDir);
+  return collected;
+}
+
 // ─── Add app to existing monorepo ───
 
 export async function addApp() {

package/src/create/index.mjs

@@ -2,6 +2,11 @@
 
 import { parseArgs } from './cli-args.js';
 import { createProject, addApp, addComponent } from './generator.js';
+import { allPlugins } from './plugins/index.js';
+import { CREATE_PLATFORMS, CREATE_STRUCTURES } from '../constants.js';
+
+const PLUGIN_NAMES = allPlugins.map((p) => p.name);
+const PLUGINS_LIST = PLUGIN_NAMES.join(', ');
 
 export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next.js / Flutter)
 
@@ -11,11 +16,12 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
   sh-ui create add-component <name> [--app <name>]
 
 옵션:
-  --platform <next|flutter>          타겟 플랫폼
-  --structure <standalone|monorepo>  Next.js 프로젝트 구조 (next 일 때)
-  --plugins <a,b>                    플러그인 (sentry, next-intl, auth-jwt). 미지정/"" → 없음
+  --platform <${CREATE_PLATFORMS.join('|')}>          타겟 플랫폼
+  --structure <${CREATE_STRUCTURES.join('|')}>  Next.js 프로젝트 구조 (next 일 때)
+  --plugins <a,b>                    플러그인 (${PLUGINS_LIST}). 미지정/"" → 없음
   --theme <base64>                   테마 JSON (base64). 선택
   --yes                              디렉토리 덮어쓰기 + 모노레포 기본값 자동 채택
+  --dry-run                          파일을 쓰지 않고 작성될 파일 목록만 출력
   -h, --help                         이 도움말
 
 예 (대화형):
@@ -23,7 +29,7 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
 
 예 (비대화형 / 에이전트 / CI):
   sh-ui create my-app --platform next --structure standalone --yes
-  sh-ui create my-app --platform next --structure monorepo --plugins sentry,next-intl,auth-jwt --yes
+  sh-ui create my-app --platform next --structure monorepo --plugins ${PLUGIN_NAMES.slice(0, 3).join(',')} --yes
   sh-ui create my-app --platform flutter --yes
 
 비대화형 환경(TTY 없음)에서는 누락된 필수 인자가 있으면 prompt 대신 에러로 종료한다.
@@ -62,6 +68,7 @@ export async function runCreate(rest) {
       plugins: flags.plugins,
       theme: flags.theme,
       yes: flags.yes,
+      dryRun: flags.dryRun,
     });
   }
 }

package/src/create/plugins/authJwt.js

@@ -1,6 +1,8 @@
 export const authJwtPlugin = {
   name: 'auth-jwt',
   label: '쿠키 기반 JWT 인증 (refresh 자리표시자 포함)',
+  description:
+    '쿠키 기반 JWT 인증. Next 16 proxy.ts 미들웨어, refresh-aware BFF, withAuthRetry 헬퍼. refresh 본문은 placeholder — 백엔드 명세 확정 후 한 파일 채우면 자동 활성화.',
   priority: 2,
 
   // 의존성 추가 없음 — 베이스의 fetch + cookies + react-query 만 사용

package/src/create/plugins/index.js

@@ -1,9 +1,14 @@
 import { sentryPlugin } from './sentry.js';
 import { nextIntlPlugin } from './nextIntl.js';
 import { authJwtPlugin } from './authJwt.js';
+import { validatePlugins } from './pluginSchema.js';
 
 export const allPlugins = [sentryPlugin, nextIntlPlugin, authJwtPlugin];
 
+// 모듈 로드 시점에 모든 플러그인 manifest 검증 — 잘못된 형태가 있으면 즉시 실패.
+// 예: src/proxy.ts 같은 잘못된 경로, name 이 kebab-case 가 아닌 경우 등.
+validatePlugins(allPlugins);
+
 export function getPluginChoices() {
   return allPlugins.map((p) => ({
     name: p.label,

package/src/create/plugins/nextIntl.js

@@ -1,6 +1,8 @@
 export const nextIntlPlugin = {
   name: 'next-intl',
   label: 'next-intl (다국어 지원)',
+  description:
+    '다국어. 라우트 기반 로케일, NEXT_LOCALE 쿠키, BFF 가 백엔드로 Accept-Language 자동 전달.',
   priority: 2,
 
   dependencies: {

package/src/create/plugins/pluginSchema.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+
+/**
+ * 플러그인 manifest 스키마.
+ * plugins/index.js 로딩 시 모든 플러그인을 이 스키마로 validate 한다.
+ *
+ * 디자인 가드:
+ * - file path 가 'src/proxy.ts' 면 거부 — Next 16 은 root proxy.ts 만 인식하므로
+ *   (베이스 템플릿이 app/ 을 root 에 두는 한). 이런 종류의 사고를 빌드 타임에 차단.
+ */
+
+const filePath = z
+  .string()
+  .min(1)
+  .refine((p) => p !== 'src/proxy.ts', {
+    message:
+      "proxy.ts must be at root (Next 16 convention with app/ at root). " +
+      "Use 'proxy.ts' instead of 'src/proxy.ts'.",
+  })
+  .refine((p) => p !== 'src/middleware.ts', {
+    message:
+      "middleware.ts (deprecated, use proxy.ts in Next 16+) must be at root. " +
+      "Use 'middleware.ts' instead of 'src/middleware.ts'.",
+  });
+
+const wrapperFn = z
+  .function()
+  .args(z.string())
+  .returns(z.string())
+  .optional();
+
+export const PluginSchema = z.object({
+  name: z.string().regex(/^[a-z][a-z0-9-]*$/, {
+    message: 'Plugin name must be lowercase kebab-case (e.g., "auth-jwt")',
+  }),
+  label: z.string().min(1),
+  description: z.string().min(1).optional(),
+  priority: z.number().int().nonnegative(),
+
+  dependencies: z.record(z.string(), z.string()).optional(),
+  devDependencies: z.record(z.string(), z.string()).optional(),
+
+  imports: z.array(z.string()).optional(),
+  wrapExport: wrapperFn,
+
+  envVars: z.array(z.string()).optional(),
+  turboEnvVars: z.array(z.string()).optional(),
+
+  providerImports: z.array(z.string()).optional(),
+  providerWrappers: z
+    .array(
+      z.union([
+        z.object({ open: z.string(), close: z.string() }),
+        z.string(),
+      ]),
+    )
+    .optional(),
+
+  files: z.record(filePath, z.string()).optional(),
+
+  // 향후 확장 — moves, transforms, etc 는 nextIntl.js 에서 사용하므로 허용
+  moves: z.array(z.any()).optional(),
+  transforms: z.array(z.any()).optional(),
+});
+
+/**
+ * 모든 플러그인을 검증. 실패 시 첫 번째 에러로 throw.
+ */
+export function validatePlugins(plugins) {
+  for (const plugin of plugins) {
+    const result = PluginSchema.safeParse(plugin);
+    if (!result.success) {
+      const issues = result.error.issues
+        .map((i) => `  - ${i.path.join('.')}: ${i.message}`)
+        .join('\n');
+      throw new Error(
+        `Invalid plugin manifest "${plugin?.name ?? '(unknown)'}":\n${issues}`,
+      );
+    }
+  }
+}

package/src/create/plugins/sentry.js

@@ -1,6 +1,8 @@
 export const sentryPlugin = {
   name: 'sentry',
   label: 'Sentry (에러 모니터링)',
+  description:
+    '에러 모니터링. 클라/서버/엣지 init, 라우트 에러 페이지, observability 브릿지로 다른 플러그인의 5xx 자동 캡처.',
   priority: 1,
 
   dependencies: {

package/src/init.mjs

@@ -3,19 +3,22 @@ import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 
+import {
+  INIT_PLATFORMS,
+  THEME_BASES,
+  THEME_RADII,
+  THEME_MODES,
+  INIT_DEFAULTS,
+} from "./constants.js";
+
 const CHOICES = {
-  platform: ["react", "flutter"],
-  base: ["neutral", "zinc", "slate"],
-  radius: ["none", "sm", "md", "lg", "xl", "full"],
-  mode: ["light-dark", "light", "dark"],
+  platform: INIT_PLATFORMS,
+  base: THEME_BASES,
+  radius: THEME_RADII,
+  mode: THEME_MODES,
 };
 
-const DEFAULTS = {
-  platform: "react",
-  base: "neutral",
-  radius: "md",
-  mode: "light-dark",
-};
+const DEFAULTS = INIT_DEFAULTS;
 
 const PATHS = {
   react: {

package/src/mcp.mjs

@@ -29,11 +29,21 @@ import {
   getSummariesPath,
   getVersionsPath,
 } from "./paths.mjs";
+import {
+  CREATE_PLATFORMS,
+  CREATE_STRUCTURES,
+  INIT_PLATFORMS,
+  THEME_BASES,
+  THEME_RADII,
+  THEME_MODES,
+} from "./constants.js";
+import { allPlugins } from "./create/plugins/index.js";
 
-const PLATFORMS = ["react", "flutter"];
-const BASES = ["neutral", "zinc", "slate"];
-const RADII = ["none", "sm", "md", "lg", "xl", "full"];
-const MODES = ["light-dark", "light", "dark"];
+const PLATFORMS = INIT_PLATFORMS;
+const BASES = THEME_BASES;
+const RADII = THEME_RADII;
+const MODES = THEME_MODES;
+const PLUGIN_NAMES = allPlugins.map((p) => p.name);
 
 const INIT_DESCRIPTIONS = {
   platform: {
@@ -161,12 +171,12 @@ export async function startMcpServer() {
       inputSchema: {
         name: z.string().min(1)
           .describe("프로젝트 디렉토리 이름. 예: my-app"),
-        platform: z.enum(["next", "flutter"])
+        platform: z.enum(CREATE_PLATFORMS)
           .describe("타겟 플랫폼"),
-        structure: z.enum(["standalone", "monorepo"]).optional()
+        structure: z.enum(CREATE_STRUCTURES).optional()
           .describe("Next.js 구조 — platform=next 일 때 필수. standalone(단독) | monorepo(Turborepo)"),
-        plugins: z.array(z.enum(["sentry", "next-intl", "auth-jwt"])).optional()
-          .describe("Next.js 플러그인. 미지정시 빈 배열"),
+        plugins: z.array(z.enum(PLUGIN_NAMES)).optional()
+          .describe(`Next.js 플러그인 (${PLUGIN_NAMES.join(', ')}). 미지정시 빈 배열`),
         theme: z.string().optional()
           .describe("base64 인코딩된 테마 JSON (선택)"),
         cwd: z.string().optional()

package/templates/nextjs-app/package.json

@@ -30,6 +30,8 @@
     "@tailwindcss/postcss": "^4.1.18",
     "@tanstack/react-query-devtools": "^5.91.3",
     "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16",
+    "@testing-library/user-event": "^14",
     "@types/node": "^25.1.0",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",

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

@@ -0,0 +1,22 @@
+/**
+ * Date → 로케일 기반 날짜 포맷 (시간 없음).
+ */
+export const formatDate = (date: Date, locale = 'ko-KR'): string =>
+  new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(date);
+
+/**
+ * Date → 로케일 기반 날짜 + 시간 포맷 (24h).
+ */
+export const formatDateTime = (date: Date, locale = 'ko-KR'): string =>
+  new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(date);

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

@@ -0,0 +1,10 @@
+/**
+ * 숫자 → 한국 원화(KRW) 포맷. 소수점 없음.
+ * 예: 12000 → "₩12,000"
+ */
+export const formatPrice = (amount: number, locale = 'ko-KR'): string =>
+  new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: 'KRW',
+    maximumFractionDigits: 0,
+  }).format(amount);

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

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

package/templates/nextjs-app/src/shared/test/createTestQueryClient.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * 테스트 전용 QueryClient — retry/refetch 끄고 gcTime 0 으로 격리.
+ */
+export const createTestQueryClient = (): QueryClient =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        refetchOnWindowFocus: false,
+        gcTime: 0,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  });

package/templates/nextjs-app/src/shared/test/index.ts

@@ -0,0 +1,2 @@
+export { createTestQueryClient } from './createTestQueryClient';
+export { renderWithProviders } from './renderWithProviders';

package/templates/nextjs-app/src/shared/test/renderWithProviders.tsx

@@ -0,0 +1,40 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import {
+  render,
+  type RenderOptions,
+  type RenderResult,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+import { createTestQueryClient } from './createTestQueryClient';
+
+type Options = Omit<RenderOptions, 'wrapper'> & {
+  queryClient?: QueryClient;
+};
+
+type Result = RenderResult & {
+  user: ReturnType<typeof userEvent.setup>;
+  queryClient: QueryClient;
+};
+
+/**
+ * RTL render + QueryClientProvider + userEvent setup 한 번에.
+ * 추가 Provider 가 필요하면 이 파일을 직접 수정하거나 wrapper 옵션을 쓴다.
+ */
+export const renderWithProviders = (
+  ui: ReactElement,
+  options: Options = {},
+): Result => {
+  const { queryClient = createTestQueryClient(), ...rtlOptions } = options;
+
+  const Wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const result = render(ui, { wrapper: Wrapper, ...rtlOptions });
+  const user = userEvent.setup();
+
+  return { ...result, user, queryClient };
+};

package/templates/nextjs-app/src/shared/ui/FallbackBoundary/index.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import {
+  Component,
+  type ComponentType,
+  type ErrorInfo,
+  type ReactNode,
+  Suspense,
+} from 'react';
+import { QueryErrorResetBoundary } from '@tanstack/react-query';
+
+export type ErrorFallbackProps = {
+  error: Error | null;
+  resetErrorBoundary: () => void;
+};
+
+type ErrorBoundaryProps = {
+  children: ReactNode;
+  fallback?: ComponentType<ErrorFallbackProps>;
+  onReset: () => void;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+type ErrorBoundaryState = {
+  hasError: boolean;
+  error: Error | null;
+};
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError?.(error, info);
+  }
+
+  resetErrorBoundary = () => {
+    this.props.onReset();
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    const { hasError, error } = this.state;
+    const { children, fallback: Fallback } = this.props;
+
+    if (hasError && Fallback) {
+      return (
+        <Fallback error={error} resetErrorBoundary={this.resetErrorBoundary} />
+      );
+    }
+
+    return children;
+  }
+}
+
+type FallbackBoundaryProps = {
+  children: ReactNode;
+  errorFallback?: ComponentType<ErrorFallbackProps>;
+  suspenseFallback?: ReactNode;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+/**
+ * Suspense + ErrorBoundary 합성. React Query 의 reset 신호에 맞춰
+ * `errorFallback` 의 `resetErrorBoundary` 가 쿼리까지 함께 리셋한다.
+ */
+export function FallbackBoundary({
+  children,
+  errorFallback,
+  suspenseFallback,
+  onError,
+}: FallbackBoundaryProps) {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset }) => (
+        <ErrorBoundary
+          onReset={reset}
+          fallback={errorFallback}
+          onError={onError}
+        >
+          <Suspense fallback={suspenseFallback}>{children}</Suspense>
+        </ErrorBoundary>
+      )}
+    </QueryErrorResetBoundary>
+  );
+}

package/templates/nextjs-app/src/shared/ui/PrefetchBoundary/index.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import {
+  dehydrate,
+  type FetchQueryOptions,
+  HydrationBoundary,
+} from '@tanstack/react-query';
+
+import getQueryClient from '@/src/shared/lib/getQueryClient';
+
+export type FetchOptions = Pick<FetchQueryOptions, 'queryKey' | 'queryFn'>;
+
+type Props = {
+  fetchOptions?: FetchOptions[] | FetchOptions | null;
+  children: ReactNode;
+};
+
+/**
+ * RSC 에서 prefetch 를 끝낸 뒤 dehydrated state 로 클라이언트에 hydrate.
+ * 단일/배열 둘 다 받는다.
+ */
+export async function PrefetchBoundary({ fetchOptions, children }: Props) {
+  const queryClient = getQueryClient();
+
+  if (fetchOptions) {
+    const list = Array.isArray(fetchOptions) ? fetchOptions : [fetchOptions];
+    await Promise.all(list.map((opt) => queryClient.prefetchQuery(opt)));
+  }
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      {children}
+    </HydrationBoundary>
+  );
+}

package/templates/nextjs-standalone/package.json

@@ -35,6 +35,8 @@
     "@tailwindcss/postcss": "^4.1.18",
     "@tanstack/react-query-devtools": "^5.91.3",
     "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16",
+    "@testing-library/user-event": "^14",
     "@types/node": "^25.1.0",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",

package/templates/nextjs-standalone/src/shared/lib/formatDate.ts

@@ -0,0 +1,22 @@
+/**
+ * Date → 로케일 기반 날짜 포맷 (시간 없음).
+ */
+export const formatDate = (date: Date, locale = 'ko-KR'): string =>
+  new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(date);
+
+/**
+ * Date → 로케일 기반 날짜 + 시간 포맷 (24h).
+ */
+export const formatDateTime = (date: Date, locale = 'ko-KR'): string =>
+  new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(date);

package/templates/nextjs-standalone/src/shared/lib/formatPrice.ts

@@ -0,0 +1,10 @@
+/**
+ * 숫자 → 한국 원화(KRW) 포맷. 소수점 없음.
+ * 예: 12000 → "₩12,000"
+ */
+export const formatPrice = (amount: number, locale = 'ko-KR'): string =>
+  new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: 'KRW',
+    maximumFractionDigits: 0,
+  }).format(amount);

package/templates/nextjs-standalone/src/shared/lib/getQueryClient.ts

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

package/templates/nextjs-standalone/src/shared/test/createTestQueryClient.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * 테스트 전용 QueryClient — retry/refetch 끄고 gcTime 0 으로 격리.
+ */
+export const createTestQueryClient = (): QueryClient =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        refetchOnWindowFocus: false,
+        gcTime: 0,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  });

package/templates/nextjs-standalone/src/shared/test/index.ts

@@ -0,0 +1,2 @@
+export { createTestQueryClient } from './createTestQueryClient';
+export { renderWithProviders } from './renderWithProviders';

package/templates/nextjs-standalone/src/shared/test/renderWithProviders.tsx

@@ -0,0 +1,40 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import {
+  render,
+  type RenderOptions,
+  type RenderResult,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+import { createTestQueryClient } from './createTestQueryClient';
+
+type Options = Omit<RenderOptions, 'wrapper'> & {
+  queryClient?: QueryClient;
+};
+
+type Result = RenderResult & {
+  user: ReturnType<typeof userEvent.setup>;
+  queryClient: QueryClient;
+};
+
+/**
+ * RTL render + QueryClientProvider + userEvent setup 한 번에.
+ * 추가 Provider 가 필요하면 이 파일을 직접 수정하거나 wrapper 옵션을 쓴다.
+ */
+export const renderWithProviders = (
+  ui: ReactElement,
+  options: Options = {},
+): Result => {
+  const { queryClient = createTestQueryClient(), ...rtlOptions } = options;
+
+  const Wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const result = render(ui, { wrapper: Wrapper, ...rtlOptions });
+  const user = userEvent.setup();
+
+  return { ...result, user, queryClient };
+};

package/templates/nextjs-standalone/src/shared/ui/FallbackBoundary/index.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import {
+  Component,
+  type ComponentType,
+  type ErrorInfo,
+  type ReactNode,
+  Suspense,
+} from 'react';
+import { QueryErrorResetBoundary } from '@tanstack/react-query';
+
+export type ErrorFallbackProps = {
+  error: Error | null;
+  resetErrorBoundary: () => void;
+};
+
+type ErrorBoundaryProps = {
+  children: ReactNode;
+  fallback?: ComponentType<ErrorFallbackProps>;
+  onReset: () => void;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+type ErrorBoundaryState = {
+  hasError: boolean;
+  error: Error | null;
+};
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError?.(error, info);
+  }
+
+  resetErrorBoundary = () => {
+    this.props.onReset();
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    const { hasError, error } = this.state;
+    const { children, fallback: Fallback } = this.props;
+
+    if (hasError && Fallback) {
+      return (
+        <Fallback error={error} resetErrorBoundary={this.resetErrorBoundary} />
+      );
+    }
+
+    return children;
+  }
+}
+
+type FallbackBoundaryProps = {
+  children: ReactNode;
+  errorFallback?: ComponentType<ErrorFallbackProps>;
+  suspenseFallback?: ReactNode;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+/**
+ * Suspense + ErrorBoundary 합성. React Query 의 reset 신호에 맞춰
+ * `errorFallback` 의 `resetErrorBoundary` 가 쿼리까지 함께 리셋한다.
+ */
+export function FallbackBoundary({
+  children,
+  errorFallback,
+  suspenseFallback,
+  onError,
+}: FallbackBoundaryProps) {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset }) => (
+        <ErrorBoundary
+          onReset={reset}
+          fallback={errorFallback}
+          onError={onError}
+        >
+          <Suspense fallback={suspenseFallback}>{children}</Suspense>
+        </ErrorBoundary>
+      )}
+    </QueryErrorResetBoundary>
+  );
+}

package/templates/nextjs-standalone/src/shared/ui/PrefetchBoundary/index.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import {
+  dehydrate,
+  type FetchQueryOptions,
+  HydrationBoundary,
+} from '@tanstack/react-query';
+
+import getQueryClient from '@/src/shared/lib/getQueryClient';
+
+export type FetchOptions = Pick<FetchQueryOptions, 'queryKey' | 'queryFn'>;
+
+type Props = {
+  fetchOptions?: FetchOptions[] | FetchOptions | null;
+  children: ReactNode;
+};
+
+/**
+ * RSC 에서 prefetch 를 끝낸 뒤 dehydrated state 로 클라이언트에 hydrate.
+ * 단일/배열 둘 다 받는다.
+ */
+export async function PrefetchBoundary({ fetchOptions, children }: Props) {
+  const queryClient = getQueryClient();
+
+  if (fetchOptions) {
+    const list = Array.isArray(fetchOptions) ? fetchOptions : [fetchOptions];
+    await Promise.all(list.map((opt) => queryClient.prefetchQuery(opt)));
+  }
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      {children}
+    </HydrationBoundary>
+  );
+}