@kood/claude-code 0.6.6 → 0.7.0

package/templates/tanstack-start/docs/library/tanstack-start/setup.md

@@ -1,52 +1,408 @@
 # TanStack Start - 설치 및 설정
 
-## 설치
+> v1.159.4 기준
+
+---
+
+<installation>
+
+## 패키지 설치
 
 ```bash
-yarn add @tanstack/react-start @tanstack/react-router vinxi
-yarn add -D vite @vitejs/plugin-react vite-tsconfig-paths
+npm install @tanstack/react-start @tanstack/react-router react react-dom
+npm install -D vite @vitejs/plugin-react vite-tsconfig-paths typescript @types/react @types/react-dom @types/node
 ```
 
-## 설정
+**vinxi 사용 금지**: TanStack Start v1은 Vite를 직접 사용합니다.
+
+| 패키지 | 버전 | 용도 |
+|--------|------|------|
+| `@tanstack/react-start` | 최신 | Full-stack framework |
+| `@tanstack/react-router` | 최신 | File-based routing |
+| `react`, `react-dom` | 19+ | React 라이브러리 |
+| `vite` | 7+ | Build tool |
+| `@vitejs/plugin-react` | 최신 | React JSX 처리 |
+| `vite-tsconfig-paths` | 최신 | Path alias 지원 |
+
+> **참고:** `@vitejs/plugin-react` 대신 `@vitejs/plugin-react-oxc` 또는 `@vitejs/plugin-react-swc`도 사용 가능합니다.
+
+### 프로젝트 생성 (자동)
+
+```bash
+npm create @tanstack/start@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+</installation>
+
+---
+
+<vite_config>
+
+## vite.config.ts
 
 ```typescript
-// vite.config.ts
 import { defineConfig } from 'vite'
 import tsConfigPaths from 'vite-tsconfig-paths'
 import { tanstackStart } from '@tanstack/react-start/plugin/vite'
 import viteReact from '@vitejs/plugin-react'
 
 export default defineConfig({
-  server: { port: 3000 },
-  plugins: [tsConfigPaths(), tanstackStart(), viteReact()],
+  server: {
+    port: 3000,
+  },
+  plugins: [
+    tsConfigPaths(),
+    tanstackStart(),
+    // react 플러그인은 반드시 start 플러그인 뒤에 위치해야 함
+    viteReact(),
+  ],
+})
+```
+
+**플러그인 순서 (중요):**
+1. `tsConfigPaths()` - Path alias
+2. `tanstackStart()` - Server Functions, SSR
+3. `viteReact()` - JSX 처리 (반드시 start 뒤에!)
+
+### Server Function ID 커스터마이징 (실험적)
+
+```typescript
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    tanstackStart({
+      serverFns: {
+        generateFunctionId: ({ filename, functionName }) => {
+          return crypto
+            .createHash('sha1')
+            .update(`${filename}--${functionName}`)
+            .digest('hex')
+        },
+      },
+    }),
+    viteReact(),
+  ],
 })
 ```
 
+</vite_config>
+
+---
+
+<typescript_config>
+
+## tsconfig.json
+
 ```json
-// tsconfig.json
 {
   "compilerOptions": {
     "target": "ES2022",
     "module": "ESNext",
-    "moduleResolution": "bundler",
+    "moduleResolution": "Bundler",
     "strict": true,
     "jsx": "react-jsx",
-    "paths": { "@/*": ["./src/*"] }
+    "strictNullChecks": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules"]
+}
+```
+
+**주의사항:**
+- `strictNullChecks: true` - null/undefined 체크 필수
+- `jsx: "react-jsx"` - React 17+ 문법
+- `moduleResolution: "Bundler"` - Vite와 호환 (대소문자 주의)
+- `verbatimModuleSyntax` **사용 금지** - 서버 번들이 클라이언트 번들로 유출될 수 있음
+- `skipLibCheck: true` 권장
+
+</typescript_config>
+
+---
+
+<package_json>
+
+## package.json Scripts
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "start": "node .output/server/index.mjs",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit"
   }
 }
 ```
 
-## 환경 변수 검증
+| Script | 명령 | 설명 |
+|--------|------|------|
+| `dev` | `vite dev` | 개발 서버 (Hot reload) |
+| `build` | `vite build` | 프로덕션 빌드 (`.output/` 생성) |
+| `start` | `node .output/server/index.mjs` | 프로덕션 서버 |
+
+> **참고:** `package.json`에 `"type": "module"` 설정이 필요합니다.
+
+</package_json>
+
+---
+
+<required_files>
+
+## 필수 파일
+
+TanStack Start 사용에 필요한 최소 파일:
+
+### 1. Router 설정 (src/router.tsx)
+
+```typescript
+// src/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+// 매번 새 router 인스턴스를 반환하는 함수를 export해야 합니다
+export function getRouter() {
+  const router = createRouter({
+    routeTree,
+    scrollRestoration: true,
+  })
+
+  return router
+}
+```
+
+### 2. Root Route (src/routes/__root.tsx)
+
+```tsx
+// src/routes/__root.tsx
+/// <reference types="vite/client" />
+import type { ReactNode } from 'react'
+import {
+  Outlet,
+  createRootRoute,
+  HeadContent,
+  Scripts,
+} from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      { title: 'My App' },
+    ],
+  }),
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <RootDocument>
+      <Outlet />
+    </RootDocument>
+  )
+}
+
+function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+**핵심 컴포넌트:**
+- `<HeadContent />` - `<head>` 태그 안에 배치, meta/title/link 렌더링
+- `<Outlet />` - 자식 라우트 렌더링
+- `<Scripts />` - `<body>` 태그 안에 배치, 클라이언트 JavaScript 로드 (필수)
+
+### 3. Route Tree (src/routeTree.gen.ts)
+
+이 파일은 `npm run dev` 또는 `npm run build` 실행 시 **자동 생성**됩니다. 수동으로 생성하지 마세요.
+
+### 4. Start 설정 (src/start.ts) - 선택적
+
+전역 미들웨어나 Start 레벨 옵션 설정 시 필요:
+
+```typescript
+// src/start.ts
+import { createStart } from '@tanstack/react-start'
+
+export const startInstance = createStart(() => ({
+  // 전역 미들웨어, SSR 기본값 등 설정
+}))
+```
+
+</required_files>
+
+---
+
+<environment_variables>
+
+## 환경 변수 설정
+
+### .env (프로젝트 루트)
+
+```env
+# 데이터베이스
+DATABASE_URL=postgresql://user:password@localhost:5432/myapp
+
+# 서버
+API_SECRET=your-secret-key-min-32-characters-long
+
+# 클라이언트 (VITE_ prefix)
+VITE_API_BASEURL=http://localhost:3000
+VITE_ENVIRONMENT=development
+```
+
+### lib/env.ts (Zod 검증)
 
 ```typescript
-// lib/env.ts
 import { z } from 'zod'
 
-const envSchema = z.object({
-  NODE_ENV: z.enum(['development', 'production', 'test']),
+// 서버 환경변수 (process.env)
+const serverEnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
   DATABASE_URL: z.string().url(),
   API_SECRET: z.string().min(32),
 })
 
-export const env = envSchema.parse(process.env)
+export const serverEnv = serverEnvSchema.parse(process.env)
+
+// 클라이언트 환경변수 (import.meta.env)
+const clientEnvSchema = z.object({
+  VITE_API_BASEURL: z.string().url().default('http://localhost:3000'),
+  VITE_ENVIRONMENT: z.enum(['development', 'production']).default('development'),
+})
+
+export const clientEnv = clientEnvSchema.parse(import.meta.env)
+```
+
+**보안 규칙:**
+- Server Function에서만 `serverEnv` 사용
+- Loader에서 `process.env` 직접 접근 금지 (클라이언트 노출)
+- 클라이언트에서는 `clientEnv` 사용
+- `VITE_` prefix로 시작하는 환경변수만 클라이언트 노출
+
+```typescript
+// 올바른 방식: Server Function에서 검증
+export const getSecretConfig = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async () => {
+    return { secret: serverEnv.API_SECRET }
+  })
+
+// 잘못된 방식: Loader에서 직접 사용
+export const Route = createFileRoute('/config')({
+  loader: () => {
+    const secret = process.env.API_SECRET // 클라이언트에 노출!
+    return { secret }
+  },
+})
+```
+
+</environment_variables>
+
+---
+
+<project_structure>
+
+## 초기 프로젝트 구조
+
 ```
+my-app/
+├── src/
+│   ├── routes/
+│   │   ├── __root.tsx          # Root layout (html/body)
+│   │   ├── index.tsx           # /
+│   │   └── $.tsx               # Catch-all (404)
+│   ├── router.tsx              # Router 설정
+│   ├── routeTree.gen.ts        # 자동 생성 (수정 금지)
+│   ├── functions/              # 공통 Server Functions
+│   ├── middleware/             # 공통 Middleware
+│   ├── components/             # UI 컴포넌트
+│   ├── lib/
+│   │   └── env.ts             # 환경변수 검증
+│   └── database/               # Prisma
+├── vite.config.ts
+├── tsconfig.json
+├── package.json
+└── .env
+```
+
+### Server Function 파일 조직 패턴
+
+```
+src/utils/
+├── users.functions.ts   # Server Function 래퍼 (createServerFn) - 어디서든 import 가능
+├── users.server.ts      # 서버 전용 헬퍼 (DB 쿼리 등) - handler 안에서만 import
+└── schemas.ts           # 공유 검증 스키마 (클라이언트 안전)
+```
+
+> **참고:** Server Function은 정적 import가 안전합니다. 빌드 프로세스가 클라이언트 번들에서 서버 구현을 RPC 스텁으로 교체합니다. 단, 동적 import는 피하세요.
+
+</project_structure>
+
+---
+
+<verification>
+
+## 설정 확인
+
+```bash
+# 1. 개발 서버 시작
+npm run dev
+
+# 2. http://localhost:3000 접속
+
+# 3. 타입 체크
+npm run type-check
+
+# 4. 프로덕션 빌드
+npm run build
+```
+
+성공 기준:
+- 개발 서버 실행
+- Hot reload 작동
+- TypeScript 에러 없음
+- `vite build` 성공 (`.output/` 생성)
+- `routeTree.gen.ts` 자동 생성됨
+
+</verification>
+
+---
+
+<version_info>
+
+**Version:** TanStack Start/Router v1.159.4
+
+**Key Points:**
+- Vite 7+ 필수 (vinxi 사용 안함)
+- `.inputValidator()` 사용 (`.validator()` deprecated)
+- `verbatimModuleSyntax` 사용 금지
+- TypeScript `strict: true` 필수
+- `package.json`에 `"type": "module"` 필수
+- React 플러그인은 반드시 Start 플러그인 뒤에 위치
+- `routeTree.gen.ts`는 자동 생성 (수동 생성 금지)
+- Server Function 정적 import 안전, 동적 import 금지
+
+</version_info>

package/templates/tauri/CLAUDE.md

@@ -0,0 +1,189 @@
+# CLAUDE.md - Tauri
+
+> Cross-platform Desktop & Mobile App Framework
+
+<context>
+
+**Purpose:** Tauri v2 프레임워크로 데스크톱/모바일 크로스플랫폼 애플리케이션 개발을 위한 작업 지침
+
+**Scope:** Rust 백엔드 + React + TypeScript + Vite 프론트엔드 기반 크로스플랫폼 앱 (iOS, Android, Windows, macOS)
+
+**Key Features:**
+- Rust 백엔드 + 시스템 WebView (작은 바이너리 사이즈)
+- React + TypeScript + Vite 프론트엔드
+- IPC (Commands + Events) 기반 프론트엔드-백엔드 통신
+- Capabilities/Permissions 보안 모델
+- Plugin 시스템 (데스크톱 + 모바일 네이티브 확장)
+- iOS, Android, Windows, macOS, Linux 빌드
+
+</context>
+
+---
+
+<instructions>
+@docs/library/tauri/index.md
+@docs/guides/getting-started.md
+@docs/guides/mobile.md
+@docs/guides/distribution.md
+</instructions>
+
+---
+
+<forbidden>
+
+| 분류 | 금지 행동 |
+|------|----------|
+| **보안** | Capabilities 없이 Command 노출, CSP 비활성화, `'unsafe-eval'` 무분별 사용 |
+| **IPC** | 프론트엔드에서 Rust 함수 직접 호출 (invoke 사용), 민감 데이터 Event로 브로드캐스트 |
+| **상태관리** | Arc 래핑 (State<T>가 내부 처리), 비동기 코드에서 await 걸쳐 Mutex lock 유지 |
+| **모바일** | iOS 개발을 macOS 외 플랫폼에서 시도, Android 메인 스레드에서 블로킹 I/O |
+| **빌드** | `--no-verify` 또는 보안 검증 우회, WebView2 설치 skip |
+| **v1 API** | allowlist 사용 (capabilities 사용), `@tauri-apps/api/tauri` import (core 사용), Window 타입 (WebviewWindow 사용) |
+
+</forbidden>
+
+---
+
+<required>
+
+| 작업 | 필수 행동 |
+|------|----------|
+| **Command 정의** | `#[tauri::command]` 어노테이션, `tauri::generate_handler!` 등록 |
+| **프론트엔드 호출** | `invoke()` from `@tauri-apps/api/core` 사용 |
+| **보안** | Capabilities 파일 정의 (`src-tauri/capabilities/`), Permission 명시 |
+| **상태관리** | `app.manage()` + `State<T>` 패턴, 가변 상태 → `Mutex<T>` |
+| **모바일 빌드** | `tauri android init` / `tauri ios init` 먼저 실행 |
+| **Plugin 사용** | Plugin별 Permission 추가 (`src-tauri/capabilities/`) |
+| **타입 안전성** | Command 인자/반환 → `serde::Serialize`/`Deserialize` |
+| **에러 처리** | Command → `Result<T, E>` 반환, Error 타입 직렬화 가능 |
+
+</required>
+
+---
+
+<tech_stack>
+
+| 기술 | 버전 | 주의 |
+|------|------|------|
+| Tauri | 2.x | CLI: @tauri-apps/cli@latest |
+| Rust | stable | MSVC 툴체인 (Windows) |
+| React | 19.x | - |
+| TypeScript | 5.x | strict |
+| Vite | 6.x | strictPort: true |
+| @tauri-apps/api | 2.x | core, webviewWindow |
+
+</tech_stack>
+
+---
+
+<structure>
+```
+my-tauri-app/
+├── src/                    # React + TypeScript 프론트엔드
+│   ├── App.tsx
+│   ├── main.tsx
+│   └── components/
+├── src-tauri/              # Rust 백엔드
+│   ├── src/
+│   │   ├── main.rs         # 앱 엔트리, Command 등록
+│   │   ├── lib.rs          # 라이브러리 (모바일 지원)
+│   │   └── commands/       # Command 모듈
+│   ├── capabilities/       # 보안 Capabilities
+│   │   └── default.json
+│   ├── Cargo.toml
+│   ├── tauri.conf.json     # Tauri 설정
+│   ├── tauri.android.conf.json  # Android 설정
+│   └── tauri.ios.conf.json      # iOS 설정
+├── package.json
+├── vite.config.ts
+└── tsconfig.json
+```
+</structure>
+
+---
+
+<conventions>
+
+파일명: kebab-case (TS), snake_case (Rust)
+Command: snake_case (Rust) → camelCase (JS invoke)
+Config: `tauri.conf.json` (메인), `tauri.[platform].conf.json` (플랫폼별)
+Capabilities: `src-tauri/capabilities/` (JSON/TOML)
+Permissions: `<plugin>:allow-<command>`, `<plugin>:deny-<command>`
+
+</conventions>
+
+---
+
+<quick_patterns>
+
+```rust
+// Rust Command 정의
+#[tauri::command]
+async fn greet(name: String) -> Result<String, String> {
+    Ok(format!("Hello, {}!", name))
+}
+
+// State 사용
+#[tauri::command]
+async fn increment(state: State<'_, Mutex<AppState>>) -> Result<u32, String> {
+    let mut s = state.lock().unwrap();
+    s.counter += 1;
+    Ok(s.counter)
+}
+
+// main.rs에 등록
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_shell::init())
+        .setup(|app| {
+            app.manage(Mutex::new(AppState { counter: 0 }));
+            Ok(())
+        })
+        .invoke_handler(tauri::generate_handler![greet, increment])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+```typescript
+// 프론트엔드 invoke
+import { invoke } from '@tauri-apps/api/core';
+
+const greeting = await invoke<string>('greet', { name: 'World' });
+
+// Event 리스닝
+import { listen } from '@tauri-apps/api/event';
+const unlisten = await listen<string>('download-progress', (event) => {
+  console.log(event.payload);
+});
+```
+
+```json
+// src-tauri/capabilities/default.json
+{
+  "identifier": "default",
+  "description": "기본 앱 권한",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "shell:allow-open"
+  ]
+}
+```
+
+</quick_patterns>
+
+---
+
+<docs_structure>
+```
+docs/
+├── guides/
+│   ├── getting-started.md   # 설치, 프로젝트 생성, 개발 시작
+│   ├── mobile.md            # iOS/Android 개발 가이드
+│   └── distribution.md      # 빌드, 코드 서명, 배포
+└── library/
+    └── tauri/
+        └── index.md         # Tauri 핵심 API + IPC + Security
+```
+</docs_structure>