@su-record/vibe 2.4.72 → 2.4.76

package/languages/typescript-nextjs.md

@@ -1,40 +1,41 @@
-# ⚡ TypeScript + Next.js 품질 규칙
+# TypeScript + Next.js Quality Rules
 
-## 핵심 원칙 (core + React에서 상속)
+## Core Principles (inherited from core + React)
 
 ```markdown
-✅ 단일 책임 (SRP)
-✅ 중복 제거 (DRY)
-✅ 재사용성
-✅ 낮은 복잡도
-✅ 함수 ≤ 30줄, JSX ≤ 50줄
-✅ React 규칙 모두 적용
+# Core Principles (inherited from core + React)
+Single Responsibility (SRP)
+No Duplication (DRY)
+Reusability
+Low Complexity
+Function <= 30 lines, JSX <= 50 lines
+All React rules apply
 ```
 
-## Next.js 특화 규칙
+## Next.js Specific Rules
 
-### 1. App Router (Next.js 13+) 우선
+### 1. App Router (Next.js 13+) First
 
 ```typescript
-// ✅ App Router 구조
+// Good: App Router structure
 app/
-├── layout.tsx              # 루트 레이아웃
-├── page.tsx                # 홈 페이지
-├── loading.tsx             # 로딩 UI
-├── error.tsx               # 에러 UI
-├── not-found.tsx           # 404 페이지
+├── layout.tsx              # Root layout
+├── page.tsx                # Home page
+├── loading.tsx             # Loading UI
+├── error.tsx               # Error UI
+├── not-found.tsx           # 404 page
 ├── users/
 │   ├── page.tsx           # /users
 │   ├── [id]/
 │   │   └── page.tsx       # /users/:id
-│   └── loading.tsx        # /users 로딩
+│   └── loading.tsx        # /users loading
 └── api/
     └── users/
         └── route.ts       # API Route
 
-// ✅ 서버 컴포넌트 (기본)
+// Good: Server Component (default)
 export default async function UsersPage() {
-  // 서버에서 데이터 페칭
+  // Fetch data on server
   const users = await getUsers();
 
   return (
@@ -45,7 +46,7 @@ export default async function UsersPage() {
   );
 }
 
-// ✅ 클라이언트 컴포넌트 (필요 시에만)
+// Good: Client Component (only when needed)
 'use client';
 
 import { useState } from 'react';
@@ -57,17 +58,17 @@ export function InteractiveButton() {
 }
 ```
 
-### 2. 서버 컴포넌트 vs 클라이언트 컴포넌트
+### 2. Server Components vs Client Components
 
 ```typescript
-// ✅ 서버 컴포넌트 (권장)
-// - 데이터 페칭
-// - 환경 변수 접근
-// - DB 직접 접근
-// - 민감한 정보 처리
+// Good: Server Component (recommended)
+// - Data fetching
+// - Environment variable access
+// - Direct DB access
+// - Sensitive information handling
 
 async function UserProfile({ userId }: { userId: string }) {
-  // 서버에서만 실행 (API 키 노출 안 됨)
+  // Runs only on server (API key not exposed)
   const user = await db.user.findUnique({
     where: { id: userId },
   });
@@ -75,11 +76,11 @@ async function UserProfile({ userId }: { userId: string }) {
   return <div>{user.name}</div>;
 }
 
-// ✅ 클라이언트 컴포넌트 (필요 시만)
-// - useState, useEffect 사용
-// - 이벤트 핸들러
-// - 브라우저 API
-// - 서드파티 라이브러리 (대부분)
+// Good: Client Component (only when needed)
+// - useState, useEffect usage
+// - Event handlers
+// - Browser APIs
+// - Third-party libraries (mostly)
 
 'use client';
 
@@ -90,20 +91,20 @@ function SearchBar() {
 }
 ```
 
-### 3. Data Fetching 패턴
+### 3. Data Fetching Patterns
 
 ```typescript
-// ✅ 서버 컴포넌트에서 직접 fetch
+// Good: Direct fetch in Server Component
 async function PostsPage() {
-  // 자동 캐싱, 재검증
+  // Auto caching, revalidation
   const posts = await fetch('https://api.example.com/posts', {
-    next: { revalidate: 60 }, // 60초 캐싱
+    next: { revalidate: 60 }, // 60 second cache
   }).then(res => res.json());
 
   return <PostList posts={posts} />;
 }
 
-// ✅ 병렬 데이터 페칭
+// Good: Parallel data fetching
 async function UserDashboard({ userId }: { userId: string }) {
   const [user, posts, comments] = await Promise.all([
     getUser(userId),
@@ -120,12 +121,12 @@ async function UserDashboard({ userId }: { userId: string }) {
   );
 }
 
-// ✅ 순차적 데이터 페칭 (의존 관계)
+// Good: Sequential data fetching (dependencies)
 async function UserWithPosts({ username }: { username: string }) {
-  // 1. 사용자 조회
+  // 1. Get user
   const user = await getUserByUsername(username);
 
-  // 2. 사용자 ID로 게시물 조회
+  // 2. Get posts by user ID
   const posts = await getUserPosts(user.id);
 
   return (
@@ -149,7 +150,7 @@ const createUserSchema = z.object({
   name: z.string().min(1),
 });
 
-// ✅ GET /api/users
+// Good: GET /api/users
 export async function GET(request: NextRequest) {
   try {
     const users = await db.user.findMany();
@@ -162,7 +163,7 @@ export async function GET(request: NextRequest) {
   }
 }
 
-// ✅ POST /api/users
+// Good: POST /api/users
 export async function POST(request: NextRequest) {
   try {
     const body = await request.json();
@@ -183,7 +184,7 @@ export async function POST(request: NextRequest) {
 }
 
 // app/api/users/[id]/route.ts
-// ✅ GET /api/users/:id
+// Good: GET /api/users/:id
 export async function GET(
   request: NextRequest,
   { params }: { params: { id: string } }
@@ -203,7 +204,7 @@ export async function GET(
 ### 5. Metadata & SEO
 
 ```typescript
-// ✅ 정적 메타데이터
+// Good: Static metadata
 import { Metadata } from 'next';
 
 export const metadata: Metadata = {
@@ -216,7 +217,7 @@ export const metadata: Metadata = {
   },
 };
 
-// ✅ 동적 메타데이터
+// Good: Dynamic metadata
 export async function generateMetadata({
   params,
 }: {
@@ -238,7 +239,7 @@ export async function generateMetadata({
 ### 6. Streaming & Suspense
 
 ```typescript
-// ✅ Streaming으로 빠른 초기 렌더링
+// Good: Streaming for fast initial render
 import { Suspense } from 'react';
 
 export default function Dashboard() {
@@ -246,10 +247,10 @@ export default function Dashboard() {
     <div>
       <h1>Dashboard</h1>
 
-      {/* 빠른 컴포넌트 먼저 렌더 */}
+      {/* Fast component renders first */}
       <QuickStats />
 
-      {/* 느린 컴포넌트 나중에 스트리밍 */}
+      {/* Slow component streams later */}
       <Suspense fallback={<ChartSkeleton />}>
         <SlowChart />
       </Suspense>
@@ -270,7 +271,7 @@ async function SlowChart() {
 ### 7. Server Actions
 
 ```typescript
-// ✅ Server Action (서버에서만 실행)
+// Good: Server Action (runs only on server)
 'use server';
 
 import { revalidatePath } from 'next/cache';
@@ -279,18 +280,18 @@ export async function createUser(formData: FormData) {
   const email = formData.get('email') as string;
   const name = formData.get('name') as string;
 
-  // 서버에서 직접 DB 접근
+  // Direct DB access on server
   const user = await db.user.create({
     data: { email, name },
   });
 
-  // 캐시 재검증
+  // Cache revalidation
   revalidatePath('/users');
 
   return user;
 }
 
-// ✅ 클라이언트에서 사용
+// Good: Usage on client
 'use client';
 
 import { createUser } from './actions';
@@ -309,19 +310,19 @@ export function CreateUserForm() {
 ### 8. Middleware
 
 ```typescript
-// middleware.ts (루트)
+// middleware.ts (root)
 import { NextResponse } from 'next/server';
 import type { NextRequest } from 'next/server';
 
 export function middleware(request: NextRequest) {
-  // 인증 체크
+  // Auth check
   const token = request.cookies.get('token')?.value;
 
   if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
     return NextResponse.redirect(new URL('/login', request.url));
   }
 
-  // 헤더 추가
+  // Add headers
   const response = NextResponse.next();
   response.headers.set('X-Custom-Header', 'value');
 
@@ -333,14 +334,14 @@ export const config = {
 };
 ```
 
-### 9. 환경 변수
+### 9. Environment Variables
 
 ```typescript
-// ✅ 서버 전용 환경 변수
-const dbUrl = process.env.DATABASE_URL; // 서버 컴포넌트에서만
+// Good: Server-only environment variables
+const dbUrl = process.env.DATABASE_URL; // Server components only
 const apiKey = process.env.API_SECRET_KEY;
 
-// ✅ 클라이언트 노출 환경 변수 (NEXT_PUBLIC_ 접두사)
+// Good: Client-exposed environment variables (NEXT_PUBLIC_ prefix)
 const publicUrl = process.env.NEXT_PUBLIC_API_URL;
 
 // .env.local
@@ -349,12 +350,12 @@ API_SECRET_KEY=secret123
 NEXT_PUBLIC_API_URL=https://api.example.com
 ```
 
-### 10. 이미지 최적화
+### 10. Image Optimization
 
 ```typescript
 import Image from 'next/image';
 
-// ✅ Next.js Image 컴포넌트 (자동 최적화)
+// Good: Next.js Image component (auto optimization)
 export function UserAvatar({ user }: { user: User }) {
   return (
     <Image
@@ -362,12 +363,12 @@ export function UserAvatar({ user }: { user: User }) {
       alt={user.name}
       width={100}
       height={100}
-      priority // LCP 이미지는 priority
+      priority // priority for LCP images
     />
   );
 }
 
-// ✅ 외부 이미지 (next.config.js 설정 필요)
+// Good: External images (requires next.config.js configuration)
 // next.config.js
 module.exports = {
   images: {
@@ -376,66 +377,66 @@ module.exports = {
 };
 ```
 
-## 안티패턴
+## Anti-patterns
 
 ```typescript
-// ❌ 클라이언트 컴포넌트에서 서버 전용 코드
+// Bad: Server-only code in Client Component
 'use client';
 
 function BadComponent() {
-  const data = await db.user.findMany(); // ❌ 클라이언트에서 DB 접근 불가
+  const data = await db.user.findMany(); // Bad: Cannot access DB from client
 }
 
-// ❌ 서버 컴포넌트에서 브라우저 API
+// Bad: Browser API in Server Component
 async function BadServerComponent() {
-  const width = window.innerWidth; // ❌ window는 브라우저에만 존재
+  const width = window.innerWidth; // Bad: window only exists in browser
 }
 
-// ❌ API Route에서 다른 API Route 호출
+// Bad: Calling API Route from another API Route
 export async function GET() {
-  const response = await fetch('http://localhost:3000/api/users'); // ❌
-  // 대신 직접 DB 함수 호출
-  const users = await getUsers(); // ✅
+  const response = await fetch('http://localhost:3000/api/users'); // Bad
+  // Instead, call DB function directly
+  const users = await getUsers(); // Good
 }
 
-// ❌ 환경 변수 노출
+// Bad: Exposing environment variables
 'use client';
 
 function BadClient() {
-  const apiKey = process.env.API_SECRET_KEY; // ❌ undefined (클라이언트에서)
+  const apiKey = process.env.API_SECRET_KEY; // Bad: undefined (on client)
 }
 ```
 
-## 성능 최적화
+## Performance Optimization
 
 ```typescript
-// ✅ Static Generation (SSG)
+// Good: Static Generation (SSG)
 export async function generateStaticParams() {
   const posts = await getPosts();
   return posts.map(post => ({ id: post.id }));
 }
 
-// ✅ Incremental Static Regeneration (ISR)
-export const revalidate = 60; // 60초마다 재생성
+// Good: Incremental Static Regeneration (ISR)
+export const revalidate = 60; // Regenerate every 60 seconds
 
-// ✅ Dynamic Rendering (SSR)
+// Good: Dynamic Rendering (SSR)
 export const dynamic = 'force-dynamic';
 
-// ✅ Partial Prerendering (실험적)
+// Good: Partial Prerendering (experimental)
 export const experimental_ppr = true;
 ```
 
-## 체크리스트
+## Checklist
 
-Next.js 코드 작성 시:
+When writing Next.js code:
 
-- [ ] App Router 사용 (Pages Router 지양)
-- [ ] 서버 컴포넌트 우선 (클라이언트 최소화)
-- [ ] API Route 대신 Server Action 고려
-- [ ] 메타데이터 정의 (SEO)
-- [ ] Suspense로 Streaming
-- [ ] Next.js Image 컴포넌트 사용
-- [ ] 환경 변수 올바르게 사용
-- [ ] Middleware로 인증/권한 체크
-- [ ] 캐싱 전략 설정 (revalidate)
-- [ ] TypeScript 엄격 모드
+- [ ] Use App Router (avoid Pages Router)
+- [ ] Server Components first (minimize client)
+- [ ] Consider Server Actions instead of API Routes
+- [ ] Define metadata (SEO)
+- [ ] Streaming with Suspense
+- [ ] Use Next.js Image component
+- [ ] Use environment variables correctly
+- [ ] Auth/permission check with Middleware
+- [ ] Configure caching strategy (revalidate)
+- [ ] TypeScript strict mode