sh-ui-cli 0.86.1 → 0.87.0

package/data/changelog/versions.json

@@ -2,6 +2,20 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.87.0",
+      "date": "2026-05-14",
+      "title": "Vite monorepo — apps/{name} + packages/ui/ui-core 공유 SoT",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui-cli create --platform vite --structure monorepo`** — vite 도 monorepo 진입점이 됨. ai-org 같은 단일 vite SPA 시나리오를 넘어, 여러 vite 앱이 packages/ui/ui-core 의 컴포넌트를 공유하는 워크스페이스 구조까지 1급 지원. apps/{name}/ (vite-app 템플릿) + packages/ui/ui-core/ (v0.65 단일 SoT) + packages/ui/ui-apps/ui-{name}/ (tokens-only role) 자동 emit.",
+        "**vite-app 템플릿 신설** — packages/cli/templates/vite-app/ 추가 (31 파일, base + flat + fsd overlays). nextjs-app 과 동일 패턴이지만 vite 5 + @tailwindcss/vite + vite-tsconfig-paths 기반. `@workspace/ui-core` / `@workspace/ui-{name}` workspace 별칭은 tsconfig.app.json 단일 SoT 로 핀고정, vite 빌드 타임에는 vite-tsconfig-paths 가 그대로 해석. workspace 별칭과 빌드 별칭이 어긋날 일 없음.",
+        "**generateMonorepo 가 platform 분기** — { platform: 'next' | 'vite' } 옵션 추가. vite 일 때 generateViteApp 으로 위임 (next 의 plugin pipeline / next.config 분기 없이 vite.config.ts 의 server.port 만 patch). ui-app-template + monorepo 베이스 + ui-core 는 두 플랫폼이 공유 — 코드 중복 없음.",
+        "**describeTemplate vite monorepo 분기** — monorepo 루트 + apps/{name} 베이스 + arch 오버레이 + ui-app 패키지 4 개 그룹으로 미리보기 산출. apps/docs CreateProjectDialog 와 MCP `sh_ui_describe_template` 둘 다 동일 결과 제공.",
+        "**스모크 회귀 가드** — `scenario V6` 가 vite 모노레포 스캐폴드의 파일 트리 + tsconfig workspace 별칭 치환 + ui-app role: tokens-only 확정. 빌드 사이클(`pnpm install + pnpm build`)은 Task E manual 에서 fsd/flat 양쪽 PASS — `composite: true` 와 base.json 의 `incremental: false` 충돌 + `clsx`/`tailwind-merge` 누락 두 가지를 사전 차단."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.87.0"
+    },
     {
       "version": "0.86.1",
       "date": "2026-05-14",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.86.1",
+  "version": "0.87.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

package/src/create/describeTemplate.js

@@ -72,22 +72,64 @@ export function describeTemplate(opts = {}) {
   }
 
   if (platform === 'vite') {
-    // standalone only in Phase 1. monorepo is added in Task 13.
-    const tpl = TEMPLATE_MANIFEST['vite-standalone'];
-    if (!tpl) {
-      throw new Error("Template manifest missing entry for 'vite-standalone'.");
-    }
     const safeArchName = isKnownArch(archName) ? archName : DEFAULT_ARCH;
     const archObj = getArchByName(safeArchName);
     if (!archObj.platforms.includes('vite')) {
       throw new Error(`Arch '${safeArchName}' is not compatible with vite.`);
     }
-    const baseFiles = tpl.base.slice();
-    const archFiles = (tpl.arches?.[safeArchName] ?? []).slice();
-    return finalize([
-      makeGroup('base', '베이스 (vite-standalone)', baseFiles),
-      makeGroup('arch', `Arch (${safeArchName})`, archFiles),
-    ]);
+
+    if (structure === 'standalone') {
+      const tpl = TEMPLATE_MANIFEST['vite-standalone'];
+      if (!tpl) {
+        throw new Error("Template manifest missing entry for 'vite-standalone'.");
+      }
+      const baseFiles = tpl.base.slice();
+      const archFiles = (tpl.arches?.[safeArchName] ?? []).slice();
+      return finalize([
+        makeGroup('base', '베이스 (vite-standalone)', baseFiles),
+        makeGroup('arch', `Arch (${safeArchName})`, archFiles),
+      ]);
+    }
+
+    // monorepo — vite app 변형. Next monorepo 브랜치와 동일 구조이지만 vite-app 템플릿
+    // 사용 + 플러그인 없음 (vite 는 아직 plugin 시스템 없음).
+    const appName = rawAppName || 'web';
+    const viteAppTpl = TEMPLATE_MANIFEST['vite-app'];
+    if (!viteAppTpl) {
+      throw new Error("Template manifest missing entry for 'vite-app'.");
+    }
+    const groups = [];
+
+    groups.push(makeGroup(
+      'monorepo',
+      '모노레포 루트',
+      TEMPLATE_MANIFEST['monorepo'].base.slice(),
+    ));
+
+    const prefix = `apps/${appName}/`;
+    groups.push(makeGroup(
+      `app-base`,
+      `apps/${appName} — vite-app 베이스`,
+      viteAppTpl.base.map((p) => prefix + p),
+    ));
+    const appArchFiles = (viteAppTpl.arches?.[safeArchName] ?? []).map((p) => prefix + p);
+    if (appArchFiles.length > 0) {
+      groups.push(makeGroup(
+        `app-arch`,
+        `apps/${appName} — Arch (${safeArchName})`,
+        appArchFiles,
+      ));
+    }
+
+    groups.push(makeGroup(
+      'ui-app',
+      `packages/ui/ui-apps/ui-${appName}`,
+      TEMPLATE_MANIFEST['ui-app-template'].base.map(
+        (p) => `packages/ui/ui-apps/ui-${appName}/${p}`,
+      ),
+    ));
+
+    return finalize(groups);
   }
 
   // platform === 'next'

package/src/create/generator.js

@@ -335,11 +335,7 @@ export async function createProject(options = {}) {
     if (projectType === 'standalone') {
       await generateViteStandalone(targetDir, projectName, theme, cssFramework, arch, themeBase);
     } else {
-      // monorepo path is added in Task 12. For now, fail loudly so users know.
-      throw new Error(
-        'platform=vite + structure=monorepo 는 아직 구현되지 않았습니다 (Phase 2 — v0.87 예정). ' +
-        'standalone 을 사용하거나 platform=next 로 monorepo 를 만든 뒤 vite 앱을 수동으로 추가해주세요.',
-      );
+      await generateMonorepo(targetDir, projectName, [], { yes: options.yes, theme, css: cssFramework, arch, themeBase, platform: 'vite' });
     }
 
     await finalizeProject(targetDir, { dryRun: options.dryRun });
@@ -772,7 +768,7 @@ async function generateViteStandalone(targetDir, projectName, theme, css, arch,
   await patchShUiConfig(path.join(targetDir, 'sh-ui.config.json'), css, themeBase);
 }
 
-async function generateMonorepo(targetDir, projectName, plugins, { yes = false, theme, css, arch, themeBase } = {}) {
+async function generateMonorepo(targetDir, projectName, plugins, { yes = false, theme, css, arch, themeBase, platform = 'next' } = {}) {
   await fs.copy(path.join(TEMPLATES_DIR, 'monorepo'), targetDir);
 
   // Update root package.json
@@ -803,7 +799,11 @@ async function generateMonorepo(targetDir, projectName, plugins, { yes = false,
   });
 
   const appsDir = path.join(targetDir, 'apps', appName);
-  await generateApp(appsDir, appName, port, plugins, arch, css);
+  if (platform === 'vite') {
+    await generateViteApp(appsDir, appName, port, arch, css);
+  } else {
+    await generateApp(appsDir, appName, port, plugins, arch, css);
+  }
   // generateApp 이 ui-{app} 패키지의 cssFramework 변종까지 처리. 여기선 theme + sh-ui.config.json 만.
   const uiAppDir = path.join(targetDir, 'packages', 'ui', 'ui-apps', `ui-${appName}`);
   await injectCssTheme(uiAppDir, theme);
@@ -901,6 +901,67 @@ async function generateApp(targetDir, appName, port, plugins, arch, css = 'tailw
   }
 }
 
+async function generateViteApp(targetDir, appName, port, arch, css = 'tailwind') {
+  // 베이스 (arch-neutral) + arch 오버레이 — generateApp 과 동일 패턴.
+  await fs.copy(path.join(TEMPLATES_DIR, 'vite-app'), targetDir, {
+    filter: (src) => !src.includes(`${path.sep}_arch${path.sep}`) && !src.endsWith(`${path.sep}_arch`),
+  });
+  await ensureArchCleanup(targetDir);
+  await fs.copy(
+    path.join(TEMPLATES_DIR, 'vite-app', '_arch', arch.name),
+    targetDir,
+    { overwrite: true },
+  );
+  // vite-app 의 flat overlay 는 src/ 하위 — arch.paths.layouts(next 관용) 앞에 src/ 보정.
+  // (generateViteStandalone 의 동일 인라인 가드와 같은 이유 — fsd 는 이미 src/app/layouts.)
+  const layoutsPath = arch.paths.layouts.startsWith('src/')
+    ? arch.paths.layouts
+    : `src/${arch.paths.layouts}`;
+  const sentinelPath = path.join(targetDir, `${layoutsPath}/RootLayout.tsx`);
+  if (!(await fs.pathExists(sentinelPath))) {
+    throw new Error(
+      `arch 오버레이 누락: vite-app + ${arch.name} 의 sentinel 파일(${layoutsPath}/RootLayout.tsx) 이 ${targetDir} 에 없습니다.`,
+    );
+  }
+
+  // 워크스페이스 placeholder 치환 — `ui-app-name` → `ui-{appName}`, `app-name` → `{appName}`.
+  await replaceInAllFiles(targetDir, 'ui-app-name', `ui-${appName}`);
+  await replaceInAllFiles(targetDir, 'app-name', appName);
+
+  // package.json — name + dep sort
+  const pkgPath = path.join(targetDir, 'package.json');
+  const pkg = await fs.readJson(pkgPath);
+  pkg.name = appName;
+  if (pkg.dependencies) pkg.dependencies = sortObjectKeys(pkg.dependencies);
+  if (pkg.devDependencies) pkg.devDependencies = sortObjectKeys(pkg.devDependencies);
+  await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+
+  // vite.config.ts 의 server.port 를 사용자 지정 port 로 patch.
+  // generateMonorepo 가 받은 port 가 next 의 --port 와 같은 의미로 흐른다.
+  const viteCfgPath = path.join(targetDir, 'vite.config.ts');
+  if (await fs.pathExists(viteCfgPath)) {
+    let viteCfg = await fs.readFile(viteCfgPath, 'utf-8');
+    viteCfg = viteCfg.replace(/port:\s*\d+/, `port: ${port}`);
+    await fs.writeFile(viteCfgPath, viteCfg);
+  }
+
+  // ui-{appName} 패키지 생성 — generateApp 과 동일 패턴 (ui-app-template 카피 후 placeholder 치환).
+  const monorepoRoot = path.resolve(targetDir, '..', '..');
+  const uiPkgDir = path.join(monorepoRoot, 'packages', 'ui', 'ui-apps', `ui-${appName}`);
+  if (!(await fs.pathExists(uiPkgDir))) {
+    await fs.copy(path.join(TEMPLATES_DIR, 'ui-app-template'), uiPkgDir);
+    await replaceInAllFiles(uiPkgDir, 'ui-app-name', `ui-${appName}`);
+    await replaceInAllFiles(uiPkgDir, 'app-name', appName);
+  }
+
+  // cssFramework 변종 — vite app 디렉토리 + ui-app 패키지 양쪽.
+  // 플러그인 없음 (vite 는 아직 플러그인 시스템 없음 — v0.87 스코프 밖).
+  await applyCssFrameworkVariant(targetDir, css, { isMonorepo: true, plugins: [], arch });
+  if (await fs.pathExists(uiPkgDir)) {
+    await applyCssFrameworkVariant(uiPkgDir, css, { isMonorepo: true, plugins: [], arch, isUiPackage: true });
+  }
+}
+
 /**
  * 베이스 템플릿 카피 직후 `_arch/` 잔여 정리.
  *

package/src/create/templateManifest.js

@@ -325,6 +325,47 @@ export const TEMPLATE_MANIFEST = {
       "tsconfig.json"
     ]
   },
+  "vite-app": {
+    "base": [
+      "eslint.config.js",
+      "gitignore",
+      "index.html",
+      "package.json",
+      "src/App.tsx",
+      "src/Home.tsx",
+      "src/main.tsx",
+      "tsconfig.json",
+      "tsconfig.node.json",
+      "vite.config.ts",
+      "vitest.config.ts",
+      "vitest.setup.ts"
+    ],
+    "arches": {
+      "flat": [
+        "src/App.tsx",
+        "src/components/layouts/RootLayout.tsx",
+        "src/components/providers/GlobalProvider/index.tsx",
+        "src/components/providers/index.tsx",
+        "src/components/providers/theme/ThemeProvider.tsx",
+        "src/lib/api/queryClient.ts",
+        "src/lib/hooks/useTheme.ts",
+        "src/lib/utils/utils.ts",
+        "src/main.tsx",
+        "tsconfig.app.json"
+      ],
+      "fsd": [
+        "src/App.tsx",
+        "src/app/layouts/RootLayout.tsx",
+        "src/app/providers/GlobalProvider/index.tsx",
+        "src/app/providers/theme/ThemeProvider.tsx",
+        "src/main.tsx",
+        "src/shared/api/queryClient.ts",
+        "src/shared/hooks/useTheme.ts",
+        "src/shared/lib/utils.ts",
+        "tsconfig.app.json"
+      ]
+    }
+  },
   "vite-standalone": {
     "base": [
       "CLAUDE.md",

package/src/mcp.mjs

@@ -366,7 +366,7 @@ export async function startMcpServer() {
     "sh_ui_create_project",
     {
       description:
-        "빈 폴더에 sh-ui 프로젝트 스캐폴드 — Next.js (standalone/monorepo) | Vite (standalone) | Flutter. " +
+        "빈 폴더에 sh-ui 프로젝트 스캐폴드 — Next.js (standalone/monorepo) | Vite (standalone/monorepo) | Flutter. " +
         `FSD 폴더 구조 + 토큰 + sh-ui.config.json 일괄 생성. 사용자가 '새 프로젝트' / '빈 폴더' / '스캐폴드부터' 류 요청을 하면 이 툴 사용 (Bash 로 npx ${cliName} create 직접 호출보다 우선). ` +
         "**단일 진입점** — theme/plugins/cssFramework/structure 모두 호출 시점에 정해서 한 번에 박는다. 호출 후 sh-ui.config.json/tokens.css 를 손으로 패치하지 말 것 (다음 재스캐폴드 시 유실). " +
         "산출물: theme 인자가 프리셋이면 sh-ui.config.json 의 theme.base 가 그 이름, base64 면 'custom'. paths.styles · paths.tokens 도 자동 박혀서 sh_ui_add_component 가 사후 패치 없이 동작.",

package/templates/vite-app/_arch/flat/src/App.tsx

@@ -0,0 +1,13 @@
+import { RootLayout } from '@/components/layouts/RootLayout';
+import { GlobalProvider } from '@/components/providers';
+import Home from './Home';
+
+export default function App() {
+  return (
+    <GlobalProvider>
+      <RootLayout>
+        <Home />
+      </RootLayout>
+    </GlobalProvider>
+  );
+}

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

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+
+export function RootLayout({ children }: { children: ReactNode }) {
+  return <div className="min-h-screen bg-background text-foreground">{children}</div>;
+}

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

@@ -0,0 +1,13 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import { type ReactNode, useState } from 'react';
+import { createQueryClient } from '@/lib/api/queryClient';
+import { ThemeProvider } from '../theme/ThemeProvider';
+
+export function GlobalProvider({ children }: { children: ReactNode }) {
+  const [queryClient] = useState(() => createQueryClient());
+  return (
+    <ThemeProvider>
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    </ThemeProvider>
+  );
+}

package/templates/vite-app/_arch/flat/src/components/providers/index.tsx

@@ -0,0 +1 @@
+export { GlobalProvider } from './GlobalProvider';

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

@@ -0,0 +1,59 @@
+import { createContext, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+export type Theme = 'light' | 'dark' | 'system';
+
+type ThemeContextValue = {
+  theme: Theme;
+  resolvedTheme: 'light' | 'dark';
+  setTheme: (theme: Theme) => void;
+};
+
+export const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+const STORAGE_KEY = 'theme';
+
+function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+function resolveTheme(theme: Theme): 'light' | 'dark' {
+  return theme === 'system' ? getSystemTheme() : theme;
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setThemeState] = useState<Theme>(() => {
+    if (typeof window === 'undefined') return 'system';
+    return (localStorage.getItem(STORAGE_KEY) as Theme) ?? 'system';
+  });
+
+  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>(() => resolveTheme(theme));
+
+  useEffect(() => {
+    const resolved = resolveTheme(theme);
+    setResolvedTheme(resolved);
+    document.documentElement.classList.toggle('dark', resolved === 'dark');
+  }, [theme]);
+
+  useEffect(() => {
+    if (theme !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = () => {
+      const resolved = getSystemTheme();
+      setResolvedTheme(resolved);
+      document.documentElement.classList.toggle('dark', resolved === 'dark');
+    };
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, [theme]);
+
+  const setTheme = useCallback((next: Theme) => {
+    setThemeState(next);
+    if (next === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, next);
+  }, []);
+
+  const value = useMemo(() => ({ theme, resolvedTheme, setTheme }), [theme, resolvedTheme, setTheme]);
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}

package/templates/vite-app/_arch/flat/src/lib/api/queryClient.ts

@@ -0,0 +1,12 @@
+import { QueryClient } from '@tanstack/react-query';
+
+export function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        refetchOnWindowFocus: false,
+      },
+    },
+  });
+}

package/templates/vite-app/_arch/flat/src/lib/hooks/useTheme.ts

@@ -0,0 +1,8 @@
+import { useContext } from 'react';
+import { ThemeContext } from '@/components/providers/theme/ThemeProvider';
+
+export function useTheme() {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error('useTheme must be used within a ThemeProvider');
+  return ctx;
+}

package/templates/vite-app/_arch/flat/src/lib/utils/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/vite-app/_arch/flat/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import '@workspace/ui-app-name/globals.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

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

@@ -0,0 +1,19 @@
+{
+  "extends": "@workspace/typescript-config/react-library.json",
+  "compilerOptions": {
+    "composite": true,
+    "incremental": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/lib/*": ["./src/lib/*"],
+      "@/components/*": ["./src/components/*"],
+      "@workspace/ui-app-name/*": ["../../packages/ui/ui-apps/ui-app-name/src/*"],
+      "@workspace/ui-core/*": ["../../packages/ui/ui-core/src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/templates/vite-app/_arch/fsd/src/App.tsx

@@ -0,0 +1,13 @@
+import { GlobalProvider } from '@/app/providers/GlobalProvider';
+import { RootLayout } from '@/app/layouts/RootLayout';
+import Home from './Home';
+
+export default function App() {
+  return (
+    <GlobalProvider>
+      <RootLayout>
+        <Home />
+      </RootLayout>
+    </GlobalProvider>
+  );
+}

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

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+
+export function RootLayout({ children }: { children: ReactNode }) {
+  return <div className="min-h-screen bg-background text-foreground">{children}</div>;
+}

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

@@ -0,0 +1,13 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import { type ReactNode, useState } from 'react';
+import { createQueryClient } from '@/shared/api/queryClient';
+import { ThemeProvider } from '../theme/ThemeProvider';
+
+export function GlobalProvider({ children }: { children: ReactNode }) {
+  const [queryClient] = useState(() => createQueryClient());
+  return (
+    <ThemeProvider>
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    </ThemeProvider>
+  );
+}

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

@@ -0,0 +1,59 @@
+import { createContext, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+export type Theme = 'light' | 'dark' | 'system';
+
+type ThemeContextValue = {
+  theme: Theme;
+  resolvedTheme: 'light' | 'dark';
+  setTheme: (theme: Theme) => void;
+};
+
+export const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+const STORAGE_KEY = 'theme';
+
+function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+function resolveTheme(theme: Theme): 'light' | 'dark' {
+  return theme === 'system' ? getSystemTheme() : theme;
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setThemeState] = useState<Theme>(() => {
+    if (typeof window === 'undefined') return 'system';
+    return (localStorage.getItem(STORAGE_KEY) as Theme) ?? 'system';
+  });
+
+  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>(() => resolveTheme(theme));
+
+  useEffect(() => {
+    const resolved = resolveTheme(theme);
+    setResolvedTheme(resolved);
+    document.documentElement.classList.toggle('dark', resolved === 'dark');
+  }, [theme]);
+
+  useEffect(() => {
+    if (theme !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = () => {
+      const resolved = getSystemTheme();
+      setResolvedTheme(resolved);
+      document.documentElement.classList.toggle('dark', resolved === 'dark');
+    };
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, [theme]);
+
+  const setTheme = useCallback((next: Theme) => {
+    setThemeState(next);
+    if (next === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, next);
+  }, []);
+
+  const value = useMemo(() => ({ theme, resolvedTheme, setTheme }), [theme, resolvedTheme, setTheme]);
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}

package/templates/vite-app/_arch/fsd/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import '@workspace/ui-app-name/globals.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/vite-app/_arch/fsd/src/shared/api/queryClient.ts

@@ -0,0 +1,12 @@
+import { QueryClient } from '@tanstack/react-query';
+
+export function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        refetchOnWindowFocus: false,
+      },
+    },
+  });
+}

package/templates/vite-app/_arch/fsd/src/shared/hooks/useTheme.ts

@@ -0,0 +1,8 @@
+import { useContext } from 'react';
+import { ThemeContext } from '@/app/providers/theme/ThemeProvider';
+
+export function useTheme() {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error('useTheme must be used within a ThemeProvider');
+  return ctx;
+}

package/templates/vite-app/_arch/fsd/src/shared/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/vite-app/_arch/fsd/tsconfig.app.json

@@ -0,0 +1,18 @@
+{
+  "extends": "@workspace/typescript-config/react-library.json",
+  "compilerOptions": {
+    "composite": true,
+    "incremental": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@workspace/ui-app-name/*": ["../../packages/ui/ui-apps/ui-app-name/src/*"],
+      "@workspace/ui-core/*": ["../../packages/ui/ui-core/src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/templates/vite-app/eslint.config.js

@@ -0,0 +1,3 @@
+import { config } from "@workspace/eslint-config/react-internal"
+
+export default config

package/templates/vite-app/gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.DS_Store
+*.log
+.env.local
+.env.*.local
+.vite/
+coverage/

package/templates/vite-app/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="ko" suppressHydrationWarning>
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>sh-ui app</title>
+    <script>
+      // FOUC 차단 — ThemeProvider mount 전에 첫 paint 에 dark class 박기.
+      // matrix: 'dark' → .dark, 'light' → (none), 'system'/unset → system pref.
+      try {
+        var t = localStorage.getItem('theme');
+        var d = t === 'dark' || ((!t || t === 'system') && matchMedia('(prefers-color-scheme:dark)').matches);
+        if (d) document.documentElement.classList.add('dark');
+      } catch (e) {}
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/vite-app/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "app-name",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc -b --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.90.21",
+    "@workspace/ui-app-name": "workspace:*",
+    "@workspace/ui-core": "workspace:*",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.563.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^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",
+    "@vitejs/plugin-react": "^5.0.0",
+    "@workspace/eslint-config": "workspace:^",
+    "@workspace/typescript-config": "workspace:*",
+    "eslint": "^9.39.2",
+    "jsdom": "^29.0.0",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3",
+    "vite": "^5.4.0",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^4.1.0"
+  }
+}

package/templates/vite-app/src/App.tsx

@@ -0,0 +1,5 @@
+import Home from './Home';
+
+export default function App() {
+  return <Home />;
+}

package/templates/vite-app/src/Home.tsx

@@ -0,0 +1,7 @@
+export default function Home() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center">
+      <h1 className="text-4xl font-bold">Hello World</h1>
+    </main>
+  );
+}

package/templates/vite-app/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/vite-app/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/templates/vite-app/tsconfig.node.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "types": ["node"]
+  },
+  "include": ["vite.config.ts", "vitest.config.ts", "vitest.setup.ts"]
+}

package/templates/vite-app/vite.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss(), tsconfigPaths()],
+  server: {
+    port: 3000,
+  },
+});

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

@@ -0,0 +1,13 @@
+import { defineConfig, mergeConfig } from 'vitest/config';
+import viteConfig from './vite.config';
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      environment: 'jsdom',
+      globals: true,
+      setupFiles: ['./vitest.setup.ts'],
+    },
+  }),
+);

package/templates/vite-app/vitest.setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';