sh-ui-cli 0.56.4 → 0.58.0

package/src/mcp.mjs

@@ -15,6 +15,7 @@
 //   sh_ui_get_changelog    - 변경 내역(versions.json) 반환
 //   sh_ui_encode_theme     - 토큰 객체 → base64 (사용자가 손본 톤을 영구 보관)
 //   sh_ui_decode_theme     - base64 → 토큰 객체 (기존 테마 일부만 수정 후 재인코딩)
+//   sh_ui_rename_app       - monorepo 의 앱 이름 일괄 변경 (디렉토리 + import/path)
 
 import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -27,6 +28,7 @@ import { init } from "./init.mjs";
 import { add } from "./add.mjs";
 import { list } from "./list.mjs";
 import { remove } from "./remove.mjs";
+import { renameApp } from "./rename-app.mjs";
 import { createProject } from "./create/generator.js";
 import {
   getRegistryRoot,
@@ -43,6 +45,7 @@ import {
   CSS_FRAMEWORKS_SUPPORTED,
 } from "./constants.js";
 import { allPlugins } from "./create/plugins/index.js";
+import { allArchitectures } from "./create/architectures/index.js";
 import { THEME_PRESET_NAMES } from "./create/theme/presets.js";
 import { decodeTheme } from "./create/theme/decode.js";
 import { encodeTheme } from "./create/theme/encode.js";
@@ -53,6 +56,7 @@ const RADII = THEME_RADII;
 const MODES = THEME_MODES;
 const CSS_FRAMEWORKS = CSS_FRAMEWORKS_SUPPORTED;
 const PLUGIN_NAMES = allPlugins.map((p) => p.name);
+const ARCH_NAMES = allArchitectures.map((a) => a.name);
 const THEME_PRESETS_LIST = THEME_PRESET_NAMES.join(", ");
 
 const INIT_DESCRIPTIONS = {
@@ -171,6 +175,10 @@ function buildServerInstructions(cliName) {
 - \`sh_ui_add_component\` / \`sh_ui_remove_component\` — 설치/삭제
 - \`sh_ui_get_changelog\` — 최근 변경 내역
 
+## 앱 이름 변경 (monorepo)
+
+사용자가 "apps/web 을 apps/dashboard 로 바꿔줘" 같이 모노레포 앱 이름 변경을 요청하면 \`sh_ui_rename_app\` 사용 — 손으로 6~10 군데 (디렉토리, package.json name, tsconfig paths, Dockerfile WORKDIR, next.config transpilePackages, sh-ui.config aliases, README, .github/workflows) 갈아엎지 않도록 자동화. \`dryRun: true\` 로 먼저 변경 매트릭스 보여주고 사용자 확인 후 실행 권장.
+
 ## 테마 커스터마이징 (스캐폴드 결과 톤이 마음에 안 들 때)
 
 스캐폴드 후 사용자가 "눈 아프다" / "Linear 톤으로" 같이 톤 조정을 요청하면, **\`tokens.css\` 직접 편집** + **편집 결과를 base64 로 백업** 두 단계를 같이 한다 — 그래야 다음에 같은 프로젝트를 재생성해도 톤이 보존된다.
@@ -221,6 +229,13 @@ export async function startMcpServer() {
           .describe("Next.js 구조 — platform=next 일 때 필수. standalone(단독) | monorepo(Turborepo)"),
         plugins: z.array(z.enum(PLUGIN_NAMES)).optional()
           .describe(`Next.js 플러그인 (${PLUGIN_NAMES.join(', ')}). 미지정시 빈 배열`),
+        arch: z.enum(ARCH_NAMES).optional()
+          .describe(
+            `프로젝트 아키텍처 — 플랫폼별로 사용 가능한 값이 다름. ` +
+            `현재 next 에서 사용 가능: ${allArchitectures.filter((a) => a.platforms.includes('next')).map((a) => a.name).join(', ')} (기본 fsd). ` +
+            `flutter 는 현재 arch 디스크립터 없음 (미지정 또는 host 자체 default). ` +
+            `arch 와 플러그인은 별개 — arch 는 폴더 구조/import alias 컨벤션, 플러그인은 기능.`,
+          ),
         theme: z.string().optional()
           .describe(`프리셋 이름 (${THEME_PRESETS_LIST}) 또는 base64 테마 코드. 사용자가 톤을 직접 손본 결과를 영구 보관하려면 sh_ui_encode_theme 으로 base64 를 만들어 여기에 넘긴다.`),
         cssFramework: z.enum(CSS_FRAMEWORKS).optional()
@@ -265,6 +280,7 @@ export async function startMcpServer() {
             platform: input.platform,
             structure: input.structure,
             plugins: input.plugins,
+            arch: input.arch,
             theme: input.theme,
             css: input.cssFramework,
             yes: true, // 사전 검사를 마쳤으니 generator 의 confirm 프롬프트 우회
@@ -524,6 +540,40 @@ export async function startMcpServer() {
     },
   );
 
+  // 모노레포 앱 이름 일괄 변경 — 디렉토리 이동 + import/path 패턴 치환 + lockfile 재생성.
+  // dryRun=true 면 변경 매트릭스만 반환해 AI 가 사용자에게 미리보기 가능.
+  server.registerTool(
+    "sh_ui_rename_app",
+    {
+      description:
+        "monorepo 의 앱 이름 일괄 변경 — apps/<old>/, packages/ui/ui-apps/ui-<old>/ 두 디렉토리 이동 + " +
+        "@workspace/ui-<old> / apps/<old> / --filter <old> / --app <old> / cd apps/<old> 패턴 치환 + " +
+        "사용자 코드, package.json name, tsconfig paths, Dockerfile WORKDIR, sh-ui.config.json aliases, README, .github/workflows 모두 자동 갱신. " +
+        "monorepo 전용 (pnpm-workspace.yaml 필수). dryRun 으로 변경 매트릭스 미리보기 가능. " +
+        "false-positive 방지를 위해 bare 단어(예: 'web')는 절대 치환하지 않고 컨텍스트(슬래시·공백·따옴표) 로 묶인 패턴만 처리.",
+      inputSchema: {
+        oldName: z.string().min(1).describe("현재 앱 이름 (예: 'web'). apps/<old>/ 가 존재해야 함."),
+        newName: z.string().min(1).describe("새 앱 이름 (예: 'dashboard'). 영숫자 + 하이픈만 허용."),
+        cwd: z.string().optional().describe("monorepo 루트 디렉토리. 기본 process.cwd()"),
+        dryRun: z.boolean().optional().describe("변경 매트릭스만 반환, 실제 파일 변경 X. 기본 false"),
+        skipInstall: z.boolean().optional().describe("마지막 pnpm install 생략. 기본 false"),
+      },
+    },
+    async (input) => {
+      const result = await captureConsole(() =>
+        renameApp({
+          cwd: resolveCwd(input),
+          oldName: input.oldName,
+          newName: input.newName,
+          yes: true, // MCP 컨텍스트는 비대화형 — 호출자(AI) 가 사용자 확인을 이미 받았다고 가정
+          dryRun: input.dryRun === true,
+          skipInstall: input.skipInstall === true,
+        }),
+      );
+      return textResult(result || "✓ rename-app 완료");
+    },
+  );
+
   // 변경 내역 조회 — 보너스: 사용자가 "최근 변경 알려줘" 류 요청 시
   server.registerTool(
     "sh_ui_get_changelog",

package/src/rename-app.mjs

@@ -0,0 +1,321 @@
+// monorepo 의 앱 이름 (apps/<old>/ + packages/ui/ui-apps/ui-<old>/) 을 일괄 변경.
+//
+// 디렉토리 이동 + 정해진 6개 패턴 치환을 자동화. 사용자가 손으로
+// 6~10 군데 (package.json 이름, tsconfig paths, Dockerfile WORKDIR,
+// next.config transpilePackages, sh-ui.config aliases, README, ...) 를
+// 일일이 갈아엎지 않도록.
+//
+// false-positive 방지를 위해 bare 단어 (`web`) 는 절대 치환하지 않고,
+// 컨텍스트(슬래시·따옴표·`--filter ` 공백) 로 묶인 패턴만 치환한다.
+//
+// 사용:
+//   sh-ui rename-app web dashboard            대화형 확인 후 실행
+//   sh-ui rename-app web dashboard --yes      비대화형
+//   sh-ui rename-app web dashboard --dry-run  변경 매트릭스만 출력
+
+import { existsSync, statSync } from "node:fs";
+import { readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+/** 텍스트 파일로 처리할 확장자 (전체 파일을 읽어 치환). */
+const TEXT_EXT = new Set([
+  ".ts", ".tsx", ".js", ".mjs", ".cjs",
+  ".json", ".jsonc",
+  ".css", ".scss",
+  ".md", ".mdx",
+  ".yml", ".yaml",
+  ".html", ".env", ".sh",
+]);
+
+/** 확장자 없는 텍스트 파일들 (Dockerfile 등) — 정확한 파일명으로 매칭. */
+const TEXT_BASENAMES = new Set([
+  "Dockerfile",
+  "Dockerfile.dev",
+  "Dockerfile.prod",
+  ".env",
+  ".env.example",
+  ".env.local",
+  ".gitignore",
+  ".dockerignore",
+]);
+
+/** 스캔하지 않을 디렉토리 — 빌드 산출물·캐시·의존성. */
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".next",
+  ".turbo",
+  ".git",
+  "dist",
+  "build",
+  ".cache",
+]);
+
+/** 모노레포 루트에서 추가로 스캔할 파일/디렉토리 (디렉토리 이동 외). */
+const ROOT_TARGETS = [
+  "package.json",
+  "README.md",
+  "turbo.json",
+  "docker-compose.yml",
+  "docker-compose.yaml",
+  "vercel.json",
+  ".github", // 디렉토리 — 안의 yml/yaml 파일들 스캔
+];
+
+function buildPatterns(oldName, newName) {
+  // false-positive 방지 위해 컨텍스트(/, ", ', 공백) 로 묶인 패턴만.
+  // 순서는 더 긴 패턴부터 (안 그러면 prefix 매치되어 부정확).
+  return [
+    [`@workspace/ui-${oldName}`, `@workspace/ui-${newName}`],
+    [`ui-apps/ui-${oldName}`, `ui-apps/ui-${newName}`],
+    [`packages/ui/ui-apps/ui-${oldName}`, `packages/ui/ui-apps/ui-${newName}`],
+    [`apps/${oldName}/`, `apps/${newName}/`],
+    [`apps/${oldName}"`, `apps/${newName}"`],
+    [`apps/${oldName}'`, `apps/${newName}'`],
+    [`apps/${oldName}\n`, `apps/${newName}\n`],
+    [`apps/${oldName} `, `apps/${newName} `],
+    [`--filter ${oldName} `, `--filter ${newName} `],
+    [`--filter ${oldName}\n`, `--filter ${newName}\n`],
+    [`--filter ${oldName}"`, `--filter ${newName}"`],
+    [`--filter ${oldName}'`, `--filter ${newName}'`],
+    [`--filter ${oldName}\``, `--filter ${newName}\``],
+    [`--app ${oldName} `, `--app ${newName} `],
+    [`--app ${oldName}\n`, `--app ${newName}\n`],
+    [`--app ${oldName}"`, `--app ${newName}"`],
+    [`--app ${oldName}'`, `--app ${newName}'`],
+    [`--app ${oldName}\``, `--app ${newName}\``],
+  ];
+}
+
+/** package.json 내부의 정확한 name 필드만 따로 처리 (정규식 1개). */
+function rewritePackageJsonName(content, oldName, newName) {
+  // "name": "old" 또는 "name": "@workspace/ui-old" 두 케이스.
+  // app 자체의 name 은 정확히 oldName 이어야 매칭.
+  return content.replace(
+    new RegExp(`"name"\\s*:\\s*"${escapeRegex(oldName)}"`),
+    `"name": "${newName}"`,
+  );
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** 한 파일의 텍스트 치환. 변경 횟수 + 새 내용 반환. */
+function applyPatternsToContent(content, patterns, oldName, newName) {
+  let next = content;
+  let hits = 0;
+  for (const [from, to] of patterns) {
+    if (next.includes(from)) {
+      const before = next;
+      next = next.split(from).join(to);
+      hits += (before.length - next.length) / (from.length - to.length) || 0;
+    }
+  }
+  // package.json name 필드도 (별도 처리 — 패턴에 안 잡힘)
+  const afterPkg = rewritePackageJsonName(next, oldName, newName);
+  if (afterPkg !== next) {
+    hits += 1;
+    next = afterPkg;
+  }
+  return { content: next, hits };
+}
+
+function isTextFile(filePath) {
+  const base = filePath.split("/").pop();
+  if (!base) return false;
+  if (TEXT_BASENAMES.has(base)) return true;
+  const dot = base.lastIndexOf(".");
+  if (dot < 0) return false;
+  return TEXT_EXT.has(base.slice(dot));
+}
+
+/** 디렉토리 재귀 순회. SKIP_DIRS 는 건너뜀. 텍스트 파일 경로 yield. */
+async function* walkTextFiles(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      yield* walkTextFiles(full);
+    } else if (entry.isFile()) {
+      if (isTextFile(full)) yield full;
+    }
+  }
+}
+
+/** Symlink 안 따라가는 단순 안전한 fs.rename. cross-device 시 fallback 없음 (모노레포 내부). */
+async function moveDir(from, to) {
+  await rename(from, to);
+}
+
+async function confirm(message) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ans = await rl.question(`${message} [y/N] `);
+    return /^y(es)?$/i.test(ans.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+function runPnpmInstall(cwd) {
+  console.log("\npnpm install — workspace 링크 재생성");
+  return new Promise((ok, bad) => {
+    const child = spawn("pnpm", ["install"], { cwd, stdio: "inherit", shell: process.platform === "win32" });
+    child.on("error", bad);
+    child.on("exit", (code) =>
+      code === 0 ? ok() : bad(new Error(`pnpm install exited with code ${code}`)),
+    );
+  });
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} opts.oldName
+ * @param {string} opts.newName
+ * @param {boolean} [opts.yes]      — 대화형 확인 생략
+ * @param {boolean} [opts.dryRun]   — 변경 매트릭스만 출력, 실제 변경 X
+ * @param {boolean} [opts.skipInstall] — 마지막 pnpm install 생략
+ * @returns {Promise<{moves: Array<[string,string]>, edits: Array<{path:string, hits:number}>}>}
+ */
+export async function renameApp({ cwd, oldName, newName, yes = false, dryRun = false, skipInstall = false }) {
+  const root = resolve(cwd);
+
+  // ─── 환경 검증 ───
+  if (!existsSync(join(root, "pnpm-workspace.yaml"))) {
+    throw new Error(
+      `${root} 가 pnpm 모노레포 루트가 아닙니다 (pnpm-workspace.yaml 없음). rename-app 은 모노레포 전용입니다.`,
+    );
+  }
+  if (!oldName || !newName) {
+    throw new Error("oldName / newName 둘 다 필요합니다.");
+  }
+  if (oldName === newName) {
+    throw new Error(`oldName 과 newName 이 같습니다 (${oldName}).`);
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/i.test(newName)) {
+    throw new Error(`newName 은 영숫자 + 하이픈만 허용 (받은 값: ${newName}).`);
+  }
+
+  const oldAppDir = join(root, "apps", oldName);
+  const newAppDir = join(root, "apps", newName);
+  const oldUiDir = join(root, "packages", "ui", "ui-apps", `ui-${oldName}`);
+  const newUiDir = join(root, "packages", "ui", "ui-apps", `ui-${newName}`);
+
+  if (!existsSync(oldAppDir)) throw new Error(`apps/${oldName} 가 존재하지 않습니다.`);
+  if (existsSync(newAppDir)) throw new Error(`apps/${newName} 가 이미 존재합니다.`);
+
+  const hasUiPkg = existsSync(oldUiDir);
+  if (hasUiPkg && existsSync(newUiDir)) {
+    throw new Error(`packages/ui/ui-apps/ui-${newName} 가 이미 존재합니다.`);
+  }
+
+  const patterns = buildPatterns(oldName, newName);
+
+  // ─── 변경 매트릭스 계산 (디렉토리 이동 전 — 원본 경로 기준 스캔) ───
+  const moves = [[oldAppDir, newAppDir]];
+  if (hasUiPkg) moves.push([oldUiDir, newUiDir]);
+
+  const edits = [];
+
+  async function scanFile(absPath, displayPath) {
+    const raw = await readFile(absPath, "utf-8");
+    const { content, hits } = applyPatternsToContent(raw, patterns, oldName, newName);
+    if (hits > 0 && content !== raw) {
+      edits.push({ path: displayPath, abs: absPath, content, hits });
+    }
+  }
+
+  // 두 패키지 디렉토리 (원본 경로) 안 텍스트 파일들
+  for await (const file of walkTextFiles(oldAppDir)) {
+    await scanFile(file, relative(root, file));
+  }
+  if (hasUiPkg) {
+    for await (const file of walkTextFiles(oldUiDir)) {
+      await scanFile(file, relative(root, file));
+    }
+  }
+
+  // 루트 추가 타겟
+  for (const target of ROOT_TARGETS) {
+    const abs = join(root, target);
+    if (!existsSync(abs)) continue;
+    const stat = statSync(abs);
+    if (stat.isDirectory()) {
+      for await (const file of walkTextFiles(abs)) {
+        await scanFile(file, relative(root, file));
+      }
+    } else if (stat.isFile() && isTextFile(abs)) {
+      await scanFile(abs, relative(root, abs));
+    }
+  }
+
+  // ─── 미리보기 출력 ───
+  console.log(`\n📦 ${oldName} → ${newName}`);
+  console.log("\n디렉토리 이동:");
+  for (const [from, to] of moves) {
+    console.log(`  ${relative(root, from)} → ${relative(root, to)}`);
+  }
+  console.log(`\n파일 내용 수정 (${edits.length}개):`);
+  for (const e of edits) {
+    console.log(`  ${e.path} (${e.hits}곳)`);
+  }
+  if (edits.length === 0) {
+    console.log("  (없음)");
+  }
+
+  if (dryRun) {
+    console.log("\n--dry-run 모드 — 실제 변경하지 않았습니다.");
+    return { moves, edits: edits.map(({ path, hits }) => ({ path, hits })) };
+  }
+
+  // ─── 확인 ───
+  if (!yes) {
+    const ok = await confirm("\n계속 진행할까요?");
+    if (!ok) {
+      console.log("취소했습니다.");
+      return { moves: [], edits: [] };
+    }
+  }
+
+  // ─── 디렉토리 이동 먼저 ───
+  for (const [from, to] of moves) {
+    await moveDir(from, to);
+  }
+
+  // ─── 파일 내용 수정 (이동된 새 경로로 매핑) ───
+  for (const edit of edits) {
+    let newAbs = edit.abs;
+    if (newAbs.startsWith(oldAppDir + "/")) {
+      newAbs = newAppDir + newAbs.slice(oldAppDir.length);
+    } else if (hasUiPkg && newAbs.startsWith(oldUiDir + "/")) {
+      newAbs = newUiDir + newAbs.slice(oldUiDir.length);
+    }
+    await writeFile(newAbs, edit.content, "utf-8");
+  }
+
+  console.log(`\n✓ ${moves.length}개 디렉토리 이동, ${edits.length}개 파일 수정`);
+
+  // ─── pnpm install 로 lockfile 재생성 ───
+  if (!skipInstall) {
+    try {
+      await runPnpmInstall(root);
+      console.log("✓ pnpm install 완료 — workspace 링크 갱신됨");
+    } catch (e) {
+      console.warn(`⚠ pnpm install 실패: ${e.message}`);
+      console.warn("  수동으로 'pnpm install' 을 실행해 lockfile 을 재생성하세요.");
+    }
+  } else {
+    console.log("\n⚠ --skip-install — lockfile 재생성을 위해 'pnpm install' 을 직접 실행하세요.");
+  }
+
+  return { moves, edits: edits.map(({ path, hits }) => ({ path, hits })) };
+}

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

@@ -0,0 +1,112 @@
+import { cookies } from 'next/headers';
+import { NextResponse, type NextRequest } from 'next/server';
+
+import {
+  captureApiError,
+  logApiError,
+} from '@/lib/api/observability';
+
+const API_URL = process.env.API_URL ?? 'http://localhost:8080/api';
+const ACCESS_TOKEN_COOKIE = 'accessToken';
+const LOCALE_COOKIE = 'NEXT_LOCALE';
+
+const proxyRequest = async (
+  request: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+  method: string,
+) => {
+  const { path } = await ctx.params;
+  const apiPath = path.join('/');
+  const url = new URL(`${API_URL}/${apiPath}`);
+
+  request.nextUrl.searchParams.forEach((value, key) => {
+    url.searchParams.set(key, value);
+  });
+
+  const cookieStore = await cookies();
+  const accessToken = cookieStore.get(ACCESS_TOKEN_COOKIE)?.value;
+  const locale =
+    cookieStore.get(LOCALE_COOKIE)?.value ??
+    request.headers.get('Accept-Language') ??
+    undefined;
+
+  const headers: Record<string, string> = {};
+  if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  if (locale) headers['Accept-Language'] = locale;
+
+  let body: BodyInit | undefined;
+  if (method !== 'GET' && method !== 'HEAD') {
+    const contentType = request.headers.get('Content-Type');
+    if (contentType?.includes('multipart/form-data')) {
+      body = await request.formData();
+    } else {
+      headers['Content-Type'] = 'application/json';
+      body = await request.text();
+    }
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(url.toString(), { method, headers, body });
+  } catch (error) {
+    console.error(`[PROXY] ${method} ${url.toString()} —`, error);
+    return NextResponse.json(
+      {
+        result: 'ERROR',
+        data: null,
+        error: {
+          code: 'NETWORK_ERROR',
+          message: '서버에 연결할 수 없습니다.',
+        },
+      },
+      { status: 502 },
+    );
+  }
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    logApiError('PROXY', {
+      url: url.toString(),
+      method,
+      status: response.status,
+      requestBody: typeof body === 'string' ? body : undefined,
+      responseBody: data,
+    });
+
+    captureApiError({
+      url: url.toString(),
+      apiPath,
+      method,
+      status: response.status,
+      responseBody: data,
+    });
+  }
+
+  return NextResponse.json(data, { status: response.status });
+};
+
+export const GET = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'GET');
+
+export const POST = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'POST');
+
+export const PUT = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PUT');
+
+export const PATCH = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PATCH');
+
+export const DELETE = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'DELETE');

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

@@ -0,0 +1,16 @@
+import type { Metadata } from 'next';
+import '@workspace/ui-app-name/globals.css';
+import { RootLayout } from '@/components/layouts/RootLayout';
+
+export const metadata: Metadata = {
+  title: 'App Name',
+  description: 'App Description',
+};
+
+export default function Layout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return <RootLayout>{children}</RootLayout>;
+}

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

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import {
+  dehydrate,
+  type FetchQueryOptions,
+  HydrationBoundary,
+} from '@tanstack/react-query';
+
+import getQueryClient from '@/lib/utils/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-app/_arch/flat/components/layouts/RootLayout.tsx

@@ -0,0 +1,11 @@
+import { GlobalProvider } from '@/components/providers';
+
+export function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang='ko' suppressHydrationWarning>
+      <body>
+        <GlobalProvider>{children}</GlobalProvider>
+      </body>
+    </html>
+  );
+}

package/templates/nextjs-app/_arch/flat/components/providers/tanstack/QueryClientProvider.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { QueryClientProvider as TanstackQueryClientProvider } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+
+import { getBrowserQueryClient } from '@/lib/api/queryClient';
+
+export function QueryClientProvider({ children }: { children: ReactNode }) {
+  return (
+    <TanstackQueryClientProvider client={getBrowserQueryClient()}>
+      {children}
+    </TanstackQueryClientProvider>
+  );
+}

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

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

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

@@ -0,0 +1,25 @@
+{
+  "extends": "@workspace/typescript-config/nextjs.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/lib/*": ["./lib/*"],
+      "@/components/*": ["./components/*"],
+      "@/app/*": ["./app/*"],
+      "@workspace/ui-app-name/*": ["../../packages/ui/ui-apps/ui-app-name/src/*"]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "next.config.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}