timsquad 2.1.0 → 3.4.0

package/templates/base/skills/frontend/react/rules/_sections.md

@@ -0,0 +1,88 @@
+---
+title: React Rule Categories
+---
+
+# React Rule Categories
+
+25개 규칙을 카테고리별로 정리. TimSquad 커스텀 + Vercel react-best-practices 통합.
+
+## TimSquad Custom (tsq-)
+
+**Impact:** HIGH
+**Description:** 프로젝트 컨벤션 및 아키텍처 규칙
+
+| Rule | Description |
+|------|-------------|
+| [component-conventions](component-conventions.md) | 컴포넌트 구조 템플릿, export, 크기 제한 |
+| [state-location](state-location.md) | useState/Context/Zustand/React Query 선택 기준 |
+| [anti-patterns](anti-patterns.md) | Props Drilling, useEffect 남용, God Component |
+
+## Eliminating Waterfalls (async-)
+
+**Impact:** CRITICAL
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency.
+
+| Rule | Description |
+|------|-------------|
+| [async-parallel](async-parallel.md) | Promise.all for independent operations (2-10x) |
+| [async-defer-await](async-defer-await.md) | Start async work before awaiting |
+| [async-api-routes](async-api-routes.md) | Parallel data fetching in API routes |
+| [async-dependencies](async-dependencies.md) | Break async dependency chains |
+| [async-suspense-boundaries](async-suspense-boundaries.md) | Granular Suspense boundaries |
+
+## Bundle Size (bundle-)
+
+**Impact:** CRITICAL
+**Description:** Reducing initial bundle size improves TTI and LCP.
+
+| Rule | Description |
+|------|-------------|
+| [bundle-barrel-imports](bundle-barrel-imports.md) | Avoid barrel files, use direct imports |
+| [bundle-dynamic-imports](bundle-dynamic-imports.md) | Dynamic import for heavy components |
+| [bundle-defer-third-party](bundle-defer-third-party.md) | Defer non-critical third-party scripts |
+
+## Server-Side Performance (server-)
+
+**Impact:** HIGH
+**Description:** Optimizing server-side rendering and data fetching.
+
+| Rule | Description |
+|------|-------------|
+| [server-cache-react](server-cache-react.md) | React cache() for request dedup |
+| [server-parallel-fetching](server-parallel-fetching.md) | Parallel server data fetching |
+| [server-after-nonblocking](server-after-nonblocking.md) | after() for non-blocking work |
+
+## Re-render Optimization (rerender-)
+
+**Impact:** MEDIUM
+**Description:** Reducing unnecessary re-renders.
+
+| Rule | Description |
+|------|-------------|
+| [rerender-memo](rerender-memo.md) | React.memo for stable components |
+| [rerender-defer-reads](rerender-defer-reads.md) | Defer state reads to minimize scope |
+| [rerender-derived-state](rerender-derived-state.md) | Derive state instead of syncing |
+| [rerender-transitions](rerender-transitions.md) | useTransition for non-urgent updates |
+
+## Rendering Performance (rendering-)
+
+**Impact:** MEDIUM
+**Description:** Optimizing the rendering process.
+
+| Rule | Description |
+|------|-------------|
+| [rendering-content-visibility](rendering-content-visibility.md) | content-visibility: auto for large lists |
+| [rendering-hoist-jsx](rendering-hoist-jsx.md) | Hoist JSX out of loops/conditions |
+| [rendering-conditional-render](rendering-conditional-render.md) | Efficient conditional rendering |
+
+## JavaScript Performance (js-)
+
+**Impact:** LOW-MEDIUM
+**Description:** Micro-optimizations for hot paths.
+
+| Rule | Description |
+|------|-------------|
+| [js-index-maps](js-index-maps.md) | Pre-index data with Maps |
+| [js-early-exit](js-early-exit.md) | Early return for cheaper checks first |
+| [js-set-map-lookups](js-set-map-lookups.md) | Set/Map for O(1) lookups |
+| [js-combine-iterations](js-combine-iterations.md) | Combine array iterations |

package/templates/base/skills/frontend/react/rules/anti-patterns.md

@@ -0,0 +1,67 @@
+---
+title: Anti-Patterns
+impact: MEDIUM
+tags: anti-pattern, performance, useEffect
+---
+
+## Anti-Patterns
+
+### 1. useEffect for Derived State
+
+**Incorrect:**
+```tsx
+const [items, setItems] = useState([]);
+const [total, setTotal] = useState(0);
+
+useEffect(() => {
+  setTotal(items.reduce((sum, i) => sum + i.price, 0));
+}, [items]);
+```
+
+**Correct:**
+```tsx
+const total = useMemo(
+  () => items.reduce((sum, i) => sum + i.price, 0),
+  [items]
+);
+```
+
+### 2. Inline Object/Array in JSX
+
+**Incorrect:**
+```tsx
+// 매 렌더링마다 새 참조 → memo 무효화
+<Child style={{ color: 'red' }} items={[1, 2, 3]} />
+```
+
+**Correct:**
+```tsx
+const style = useMemo(() => ({ color: 'red' }), []);
+const items = useMemo(() => [1, 2, 3], []);
+<Child style={style} items={items} />
+```
+
+### 3. Props Drilling (3+ levels)
+
+3단계 이상 Props 전달 → Context 또는 Zustand 사용.
+
+### 4. God Component (500+ lines)
+
+하나의 거대한 컴포넌트 → 작은 단위로 분리, 훅으로 로직 추출.
+
+### 5. Stale Closure in Callbacks
+
+**Incorrect:**
+```tsx
+const [items, setItems] = useState(initialItems);
+const addItems = useCallback((newItems: Item[]) => {
+  setItems([...items, ...newItems]); // items 참조 고정됨
+}, [items]); // items 변경마다 재생성
+```
+
+**Correct:**
+```tsx
+const addItems = useCallback((newItems: Item[]) => {
+  setItems(curr => [...curr, ...newItems]); // 함수형 setState
+}, []); // 의존성 없음, 안정적
+```

package/templates/base/skills/frontend/react/rules/async-api-routes.md

@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).

package/templates/base/skills/frontend/react/rules/async-defer-await.md

@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+
+  const permissions = await fetchPermissions(userId)
+
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.

package/templates/base/skills/frontend/react/rules/async-dependencies.md

@@ -0,0 +1,36 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

package/templates/base/skills/frontend/react/rules/async-parallel.md

@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```

package/templates/base/skills/frontend/react/rules/async-suspense-boundaries.md

@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.

package/templates/base/skills/frontend/react/rules/bundle-barrel-imports.md

@@ -0,0 +1,59 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (imports only what you need):**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative (Next.js 13.5+):**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)

package/templates/base/skills/frontend/react/rules/bundle-defer-third-party.md

@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```

package/templates/base/skills/frontend/react/rules/bundle-dynamic-imports.md

@@ -0,0 +1,35 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, next-dynamic
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```

package/templates/base/skills/frontend/react/rules/component-conventions.md

@@ -0,0 +1,74 @@
+---
+title: Component Conventions
+impact: HIGH
+tags: component, structure, naming
+---
+
+## Component Conventions
+
+프로젝트 전체에서 일관된 컴포넌트 구조를 유지하기 위한 규칙.
+
+### Structure Template
+
+```tsx
+// 1. 타입 정의
+interface Props { ... }
+
+// 2. 컴포넌트
+export function ComponentName({ prop1, prop2 }: Props) {
+  // 3. 훅 (순서 중요 - 항상 최상위)
+  const [state, setState] = useState();
+  const { data } = useQuery();
+  const router = useRouter();
+
+  // 4. 파생 값
+  const derivedValue = useMemo(() => ..., [deps]);
+
+  // 5. 이벤트 핸들러
+  const handleClick = useCallback(() => ..., [deps]);
+
+  // 6. 이펙트 (최소화)
+  useEffect(() => ..., [deps]);
+
+  // 7. Early Return
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+
+  // 8. 메인 렌더링
+  return ( ... );
+}
+```
+
+### Rules
+
+**Incorrect:**
+```tsx
+// default export, 타입 미정의
+export default function UserCard({ user, onEdit }) {
+  return <div>{user.name}</div>;
+}
+```
+
+**Correct:**
+```tsx
+interface UserCardProps {
+  user: User;
+  onEdit?: (user: User) => void;
+}
+
+export function UserCard({ user, onEdit }: UserCardProps) {
+  return (
+    <div className="user-card">
+      <Avatar src={user.avatar} alt={user.name} />
+      <h3>{user.name}</h3>
+      {onEdit && <Button onClick={() => onEdit(user)}>Edit</Button>}
+    </div>
+  );
+}
+```
+
+### Limits
+
+- 컴포넌트: **200줄 이하** (초과 시 분리)
+- **named export**: `export function` (default export 금지)
+- **forwardRef**: ref 전달이 필요한 컴포넌트는 필수

package/templates/base/skills/frontend/react/rules/js-combine-iterations.md

@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```