@kood/claude-code 0.1.0

package/templates/tanstack-start/docs/guides/getting-started.md

@@ -0,0 +1,304 @@
+# Getting Started
+
+TanStack Start 프로젝트 시작 가이드입니다.
+
+## Prerequisites
+
+- Node.js 18+
+- Yarn
+- Claude Code CLI
+
+## Project Setup
+
+### 1. Create TanStack Start Project
+
+```bash
+npx create-tsrouter-app@latest my-app --template start
+cd my-app
+```
+
+### 2. Install Dependencies
+
+```bash
+yarn install
+```
+
+### 3. Add Essential Packages
+
+```bash
+# Database (Prisma 7.x)
+yarn add @prisma/client@7
+yarn add -D prisma@7
+
+# Validation (Zod 4.x)
+yarn add zod
+
+# TanStack Query
+yarn add @tanstack/react-query
+
+# UI (optional)
+yarn add tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+### 4. Initialize Prisma
+
+```bash
+npx prisma init
+```
+
+## Project Structure
+
+```
+my-app/
+├── src/
+│   ├── routes/
+│   │   ├── __root.tsx
+│   │   ├── index.tsx
+│   │   └── users/
+│   │       ├── index.tsx
+│   │       ├── route.tsx           # 필요시 route 설정
+│   │       ├── -components/        # 페이지 전용 컴포넌트
+│   │       │   └── user-card.tsx
+│   │       ├── -sections/          # 섹션 분리 (복잡한 경우)
+│   │       │   ├── user-list-section.tsx
+│   │       │   └── user-filter-section.tsx
+│   │       └── -hooks/             # 페이지 전용 훅
+│   │           ├── use-users.ts
+│   │           └── use-user-filter.ts
+│   ├── components/                 # 공통 컴포넌트
+│   │   └── ui/
+│   │       ├── button.tsx
+│   │       └── input.tsx
+│   ├── database/                   # 데이터베이스 관련
+│   │   └── prisma.ts               # Prisma Client 인스턴스
+│   ├── services/                   # 도메인별 SDK/서비스 레이어
+│   │   ├── user/
+│   │   │   ├── index.ts            # 진입점 (re-export)
+│   │   │   ├── schemas.ts          # Zod 스키마
+│   │   │   ├── queries.ts          # GET 요청
+│   │   │   └── mutations.ts        # POST 요청
+│   │   └── auth/
+│   │       ├── index.ts
+│   │       ├── schemas.ts
+│   │       ├── queries.ts
+│   │       └── mutations.ts
+│   ├── lib/                        # 공통 유틸리티
+│   │   ├── query-client.ts
+│   │   └── utils.ts
+│   └── styles/
+│       └── app.css
+├── generated/
+│   └── prisma/                     # Prisma Client 출력
+├── prisma/
+│   └── schema.prisma
+├── app.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+## Route Folder Convention
+
+TanStack Start에서 `-` 접두사는 라우트에서 제외됩니다:
+
+```
+routes/users/
+├── index.tsx              # /users 페이지
+├── route.tsx              # route 설정 (loader, beforeLoad 등)
+├── -components/           # ❌ 라우트 아님, 컴포넌트 폴더
+│   └── user-card.tsx
+├── -sections/             # ❌ 라우트 아님, 섹션 폴더
+│   └── user-list-section.tsx
+└── -hooks/                # ❌ 라우트 아님, 훅 폴더
+    └── use-users.ts
+```
+
+## Core Configuration
+
+### app.config.ts
+
+```typescript
+import { defineConfig } from '@tanstack/react-start/config'
+
+export default defineConfig({
+  server: {
+    preset: 'node-server',
+  },
+})
+```
+
+### Root Route
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+import { TanStackRouterDevtools } from '@tanstack/router-devtools'
+
+export const Route = createRootRoute({
+  component: RootComponent,
+})
+
+const RootComponent = (): JSX.Element => {
+  return (
+    <>
+      <div className="min-h-screen">
+        <nav className="border-b p-4">
+          <a href="/" className="font-bold">My App</a>
+        </nav>
+        <main className="container mx-auto p-4">
+          <Outlet />
+        </main>
+      </div>
+      <TanStackRouterDevtools />
+    </>
+  )
+}
+```
+
+### Home Route
+
+```tsx
+// src/routes/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: HomePage,
+})
+
+const HomePage = (): JSX.Element => {
+  return (
+    <div>
+      <h1 className="text-2xl font-bold">Welcome</h1>
+    </div>
+  )
+}
+```
+
+## Services Setup
+
+### Database Setup
+
+```typescript
+// src/database/prisma.ts
+import { PrismaClient } from '../../generated/prisma'
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined
+}
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query'] : [],
+  })
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma
+}
+```
+
+### Query Client
+
+```typescript
+// src/lib/query-client.ts
+import { QueryClient } from '@tanstack/react-query'
+
+export const createQueryClient = (): QueryClient => {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        retry: 1,
+      },
+    },
+  })
+}
+```
+
+### User Service (도메인 폴더 구조)
+
+```typescript
+// src/services/user/schemas.ts
+import { z } from 'zod'
+
+export const createUserSchema = z.object({
+  email: z.email(),
+  name: z.string().min(1).max(100).trim(),
+})
+
+export const updateUserSchema = z.object({
+  id: z.string(),
+  email: z.email().optional(),
+  name: z.string().min(1).max(100).trim().optional(),
+})
+
+export type CreateUserInput = z.infer<typeof createUserSchema>
+export type UpdateUserInput = z.infer<typeof updateUserSchema>
+```
+
+```typescript
+// src/services/user/queries.ts
+import { createServerFn } from '@tanstack/react-start'
+import { prisma } from '@/database/prisma'
+
+export const getUsers = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    return prisma.user.findMany({
+      orderBy: { createdAt: 'desc' },
+    })
+  })
+
+export const getUserById = createServerFn({ method: 'GET' })
+  .handler(async ({ data: id }: { data: string }) => {
+    const user = await prisma.user.findUnique({ where: { id } })
+    if (!user) throw new Error('User not found')
+    return user
+  })
+```
+
+```typescript
+// src/services/user/mutations.ts
+import { createServerFn } from '@tanstack/react-start'
+import { prisma } from '@/database/prisma'
+import { createUserSchema, updateUserSchema } from './schemas'
+
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(createUserSchema)
+  .handler(async ({ data }) => {
+    return prisma.user.create({ data })
+  })
+
+export const updateUser = createServerFn({ method: 'POST' })
+  .inputValidator(updateUserSchema)
+  .handler(async ({ data }) => {
+    const { id, ...updateData } = data
+    return prisma.user.update({ where: { id }, data: updateData })
+  })
+
+export const deleteUser = createServerFn({ method: 'POST' })
+  .handler(async ({ data: id }: { data: string }) => {
+    return prisma.user.delete({ where: { id } })
+  })
+```
+
+```typescript
+// src/services/user/index.ts
+export * from './schemas'
+export * from './queries'
+export * from './mutations'
+```
+
+## Development Commands
+
+| Command | Description |
+|---------|-------------|
+| `yarn dev` | Start development server |
+| `yarn build` | Build for production |
+| `yarn start` | Start production server |
+| `yarn test` | Run tests |
+| `yarn lint` | Check code quality |
+
+## Next Steps
+
+- [Best Practices](./best-practices.md) - 개발 모범 사례
+- [Project Templates](./project-templates.md) - 프로젝트 템플릿

package/templates/tanstack-start/docs/guides/husky-lint-staged.md

@@ -0,0 +1,303 @@
+# Husky + lint-staged
+
+> Git 커밋 시 자동 코드 검사 및 포맷팅
+
+---
+
+## 🚀 Quick Reference
+
+### 설치 (복사용)
+
+```bash
+# 패키지 설치
+yarn add -D husky lint-staged
+
+# Husky 초기화
+npx husky init
+
+# pre-commit 훅 설정
+echo "npx lint-staged" > .husky/pre-commit
+```
+
+---
+
+## 설치 단계별 가이드
+
+### 1. 패키지 설치
+
+```bash
+yarn add -D husky lint-staged
+```
+
+### 2. Husky 초기화
+
+```bash
+npx husky init
+```
+
+이 명령어는:
+- `.husky/` 디렉토리 생성
+- `package.json`에 `prepare` 스크립트 추가
+- 기본 `pre-commit` 훅 생성
+
+### 3. pre-commit 훅 설정
+
+```bash
+echo "npx lint-staged" > .husky/pre-commit
+```
+
+---
+
+## 설정 파일
+
+### package.json
+
+```json
+{
+  "scripts": {
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "prettier --write"
+    ],
+    "*.{json,yml,yaml}": [
+      "prettier --write"
+    ],
+    "*.{css,scss}": [
+      "prettier --write"
+    ]
+  }
+}
+```
+
+### 또는 .lintstagedrc.json (별도 파일)
+
+```json
+{
+  "*.{js,jsx,ts,tsx}": [
+    "prettier --write"
+  ],
+  "*.{json,yml,yaml}": [
+    "prettier --write"
+  ],
+  "*.{css,scss}": [
+    "prettier --write"
+  ]
+}
+```
+
+**주의**: `*.md` 파일은 lint-staged에서 제외 (Prettier가 테이블 등을 이상하게 변형함)
+
+---
+
+## 고급 설정
+
+### TypeScript 타입 체크 포함
+
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "prettier --write",
+      "bash -c 'tsc --noEmit'"
+    ],
+    "*.{js,jsx}": [
+      "prettier --write"
+    ]
+  }
+}
+```
+
+### ESLint 포함 (선택)
+
+```json
+{
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}
+```
+
+### 테스트 포함 (선택)
+
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "prettier --write",
+      "vitest related --run"
+    ]
+  }
+}
+```
+
+---
+
+## 디렉토리 구조
+
+```
+project/
+├── .husky/
+│   ├── _/
+│   │   └── husky.sh
+│   └── pre-commit        # 커밋 전 실행
+├── package.json          # lint-staged 설정
+└── .prettierrc           # Prettier 설정
+```
+
+---
+
+## .husky/pre-commit 예시
+
+### 기본 (lint-staged만)
+
+```bash
+npx lint-staged
+```
+
+### 추가 검사 포함
+
+```bash
+#!/bin/sh
+
+# lint-staged 실행
+npx lint-staged
+
+# 타입 체크 (전체)
+echo "Running type check..."
+npx tsc --noEmit
+```
+
+---
+
+## 작동 흐름
+
+```
+git commit -m "feat: 새 기능"
+       ↓
+.husky/pre-commit 실행
+       ↓
+lint-staged 실행
+       ↓
+스테이징된 파일만 처리:
+  - *.ts, *.tsx → prettier --write
+  - *.json, *.md → prettier --write
+       ↓
+변경된 파일 자동 스테이징
+       ↓
+커밋 완료
+```
+
+---
+
+## 문제 해결
+
+### 훅이 실행되지 않을 때
+
+```bash
+# Husky 재설치
+rm -rf .husky
+npx husky init
+echo "npx lint-staged" > .husky/pre-commit
+```
+
+### 권한 문제
+
+```bash
+chmod +x .husky/pre-commit
+```
+
+### lint-staged 캐시 문제
+
+```bash
+# 캐시 삭제
+rm -rf node_modules/.cache/lint-staged
+```
+
+### 훅 우회 (긴급 시에만)
+
+```bash
+git commit -m "fix: 긴급 수정" --no-verify
+```
+
+**주의**: `--no-verify`는 정말 긴급한 상황에서만 사용
+
+---
+
+## 팀 설정
+
+### 새 팀원 온보딩
+
+```bash
+# 클론 후 실행
+yarn install  # prepare 스크립트가 자동으로 husky 설정
+```
+
+### CI/CD에서 Husky 비활성화
+
+```bash
+# CI 환경에서
+HUSKY=0 yarn install
+```
+
+또는 package.json:
+
+```json
+{
+  "scripts": {
+    "prepare": "husky || true"
+  }
+}
+```
+
+---
+
+## 권장 설정 조합
+
+### 최소 설정
+
+```json
+{
+  "lint-staged": {
+    "*": ["prettier --write --ignore-unknown"]
+  }
+}
+```
+
+### 표준 설정 (권장)
+
+```json
+{
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": ["prettier --write"],
+    "*.{json,yml,yaml,css,scss}": ["prettier --write"]
+  }
+}
+```
+
+### 엄격한 설정
+
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "prettier --write",
+      "bash -c 'tsc --noEmit'"
+    ],
+    "*.{js,jsx}": ["prettier --write"],
+    "*.{json,yml,yaml,css,scss}": ["prettier --write"]
+  }
+}
+```
+
+---
+
+## 참고
+
+- [Husky 공식 문서](https://typicode.github.io/husky/)
+- [lint-staged 공식 문서](https://github.com/lint-staged/lint-staged)
+- [Prettier 설정](./prettier.md)