02-reusable-code — 범용 재사용 코드 라이브러리

프로젝트에 복사하여 사용하는 원자적 코드 부품 라이브러리 (TypeScript/React)

개요

단독으로 동작하는 최소 단위의 코드 부품 — UI 컴포넌트, 커스텀 훅, 유틸리티 함수, 서비스 패턴 등을 관리합니다. 도메인에 무관하며 조합하여 사용할 수 있습니다.

3계층 모델에서의 위치

02-reusable-design  ← "재료" (색상, 폰트, 애니메이션 정의)
        │ 참조
02-reusable-code    ← "부품" ★ (Button, hooks, utils)
        │ 조합
02-reusable-page    ← "완성품" (Footer, Header, Hero)

계층	판단 기준	예시
design	값/설정인가?	`--color-primary: #6366f1`, `@keyframes fadeIn`
code	동작하는 코드인가?	`useDebounce()`, `<Button>`, `formatDate()`
page	화면의 한 영역인가?	`<Footer>`, `<HeroSection>`, `<Sidebar>`

code에 넣는 것

단독 UI 컴포넌트 (<Button>, <Dialog>, <Card>)
React 커스텀 훅 (useDebounce, useLocalStorage)
유틸리티 함수 (formatDate, cn, deepClone)
서비스/미들웨어 패턴 (API Client, Rate Limiter)
도메인별 패턴 (Supabase, Stripe, Next.js, 테스팅)

code에 넣지 않는 것

순수 스타일 정의 (CSS 변수, 키프레임, Tailwind 설정) → 02-reusable-design
페이지 섹션 (Header, Footer, Hero 등 완성된 영역) → 02-reusable-page

폴더 구조

02-reusable-code/
├── 01-ui-components/       # UI 컴포넌트
│   ├── _shared/            # 공통 타입(Size, Status, ColorVariant), i18n 텍스트
│   ├── feedback/           # 상태 표시 (EmptyState, ErrorState, LoadingState, Toast)
│   ├── lib/                # 유틸리티 (cn 함수 - clsx + tailwind-merge)
│   ├── shadcn-core/        # shadcn/ui 핵심 (Button, Dialog, Tabs 등)
│   ├── shadcn-form/        # shadcn/ui 폼 (Input, Select, Checkbox 등)
│   ├── shadcn-overlay/     # shadcn/ui 오버레이 (Sheet, Drawer, Popover 등)
│   ├── shadcn-nav/         # shadcn/ui 네비게이션 (Menu, Breadcrumb 등)
│   ├── shadcn-data/        # shadcn/ui 데이터 (Table, Card, Badge 등)
│   ├── shadcn-misc/        # shadcn/ui 기타 (Calendar, Carousel, Toggle 등)
│   ├── error-boundary/     # Error Boundary + 폴백 UI
│   └── web3/               # Web3 결제 컴포넌트
├── 02-hooks/               # React 커스텀 훅 (48개)
│   └── web3/               # Web3 지갑/결제 훅
├── 03-utils/               # 유틸리티 함수
│   ├── types/              # TypeScript 타입 유틸 (헬퍼, 브랜드, 유니온)
│   ├── export/             # 내보내기 (Excel, PDF, HWPX)
│   ├── web3/               # Web3 상수/타입
│   └── browser-stealth/    # 스텔스 브라우저 자동화 유틸 (Bezier 마우스, Gaussian 딜레이, 타이포)
├── 05-auth-rbac/           # 인증/권한 패턴
│   └── edge-jwt/           # Edge 호환 JWT + 비밀번호 해싱
├── 06-api-middleware/      # API 미들웨어 및 에러 처리
│   └── middleware-system/  # 범용 미들웨어 시스템 (Rate Limit, Logger, Compose)
├── 08-services/            # 서비스 레이어 패턴
│   └── web3/               # Web3 결제 검증
├── 10-stripe-patterns/     # Stripe SaaS 구독 결제 패턴
│   ├── config/             # Stripe 서버/클라이언트 설정
│   ├── api/                # 결제 API 라우트 7개
│   ├── components/         # Pricing UI, Plan Change Dialog
│   └── schema/             # Supabase DB 스키마
├── 11-state-patterns/      # 상태관리 패턴
│   ├── zustand/            # 슬라이스, Persist, Immer 패턴
│   ├── react-query/        # 쿼리 키, 낙관적 업데이트, 무한쿼리
│   └── jotai/              # Atom 패턴
├── 12-nextjs-patterns/     # Next.js App Router 패턴
│   ├── server-actions/     # Server Action (폼, 인증, 낙관적)
│   ├── route-handlers/     # API 응답 헬퍼
│   ├── streaming/          # Suspense + Error Boundary
│   ├── rsc/                # Server/Client 합성 패턴
│   └── middleware/         # 인증 미들웨어
├── 13-testing-patterns/    # 테스팅 패턴
│   ├── vitest/             # Vitest 설정
│   ├── testing-library/    # 커스텀 render
│   ├── msw/                # 요청 핸들러 + 서버 설정
│   └── playwright/         # Page Object + Fixture
├── 16-algorithm-engines/   # 알고리즘 엔진 + 캔버스 시각화
│   ├── physics/            # 물리 시뮬레이션 엔진 (Boids, N-Body)
│   └── canvas/             # React 캔버스 컴포넌트 (6개)
└── 17-verification-patterns/ # 엔티티 신뢰도 검증 (Trust Score + URL 안전성)

호환성

TypeScript: 5.0+
React: 18+
Next.js: 14+ (App Router)
Node.js: 18+
컨벤션: docs/rules/reusable-code.md 참조

사용 전 설정

1. 의존성 설치

# 공통 유틸리티 (필수)
pnpm add clsx tailwind-merge class-variance-authority lucide-react

# shadcn-core
pnpm add @radix-ui/react-slot @radix-ui/react-dialog @radix-ui/react-alert-dialog
pnpm add @radix-ui/react-tabs @radix-ui/react-avatar @radix-ui/react-tooltip
pnpm add @radix-ui/react-progress @radix-ui/react-accordion

# shadcn-form
pnpm add @radix-ui/react-checkbox @radix-ui/react-radio-group @radix-ui/react-slider
pnpm add @radix-ui/react-switch @radix-ui/react-select @radix-ui/react-label
pnpm add react-hook-form input-otp

# shadcn-overlay
pnpm add @radix-ui/react-popover @radix-ui/react-hover-card @radix-ui/react-context-menu
pnpm add vaul cmdk

# shadcn-nav
pnpm add @radix-ui/react-navigation-menu @radix-ui/react-menubar @radix-ui/react-dropdown-menu

# shadcn-data
pnpm add @radix-ui/react-scroll-area @radix-ui/react-separator @radix-ui/react-collapsible
pnpm add react-resizable-panels

# shadcn-misc
pnpm add @radix-ui/react-toggle @radix-ui/react-toggle-group @radix-ui/react-aspect-ratio
pnpm add react-day-picker embla-carousel-react sonner

2. 경로 별칭 설정 (tsconfig.json)

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. cn 유틸리티 복사

03-utils/cn.ts를 src/lib/utils.ts로 복사

출처 기록

날짜	프로젝트	추출 항목
2026-02-16	GitHub-커뮤니티	훅 28개, 유틸 10개, 상태관리 7개, Next.js 7개, 테스팅 6개, 타입 3개, Error Boundary 3개
2026-01-27	shadcn/ui	UI 컴포넌트 44개 (v4 new-york style)
2026-01-27	(레퍼런스 코드)	Web3 USDC/USDT 결제 - 훅 2개, UI 1개, 서비스 1개, 유틸 2개
2026-01-27	260111-tiny-house	유틸 4개 (currency, slug, truncate, area), 훅 1개 (useFavorite)
2025-01-27	monet-registry-main	UI 컴포넌트 12개, 훅 1개, 유틸 1개, API 패턴 3개
2026-02-15	260214 silvercare-master	UI 4개, 훅 4개, 유틸 1개, 서비스 1개 (Cloudinary)
2026-02-15	260208 kcsi-smpa	유틸 6개 (export 3개, text-analysis, chart-utils, anonymous-names)
2026-02-16	260116 secure-vault-master + monet-registry-main	Stripe SaaS 패턴 - API 7개, 컴포넌트 2개, DB 스키마, 설정 2개
2026-02-16	260116 dokiwiki-main	Edge JWT 인증 세트 3개, 미들웨어 시스템 6개
2026-02-16	260105 legal-tech-app	범용 에러 핸들링, 훅 2개 (useAutoSave, useUnsavedChangesWarning)
2026-02-16	260214 silvercare-master	API Client, Retry Policy, API Response 헬퍼

카테고리별 파일 목록

01-ui-components/_shared (공통 유틸)

파일	설명
`types.ts`	공통 타입 (Size, Status, ColorVariant, Orientation 등)
`i18n.ts`	UI 텍스트 정의 (영어 기본, 한국어 export)

01-ui-components/feedback (상태 표시 컴포넌트)

출처: silvercare-master | 추출일: 2026-02-15

컴포넌트	설명	의존성
`empty-state.tsx`	빈 데이터 플레이스홀더	`lucide-react`
`error-state.tsx`	에러 + 재시도 버튼 (i18n labels prop)	`lucide-react`
`loading-state.tsx`	스피너 + 스켈레톤 유틸	`lucide-react`
`toast.tsx`	토스트 알림 시스템	`lucide-react`

01-ui-components/lib (유틸리티)

파일	설명	의존성
`utils.ts`	`cn()` 함수 (clsx + tailwind-merge)	`clsx`, `tailwind-merge`

01-ui-components/shadcn-* (shadcn/ui 컴포넌트)

출처: shadcn/ui (MIT License) 버전: v4 (new-york style) | 추출일: 2026-01-27

shadcn-core (핵심 컴포넌트)

컴포넌트	설명	의존성
`Button`	버튼 (variant: default, destructive, outline, secondary, ghost, link, warm)	`@radix-ui/react-slot`
`Dialog`	모달 다이얼로그	`@radix-ui/react-dialog`
`Alert`	알림 메시지	-
`AlertDialog`	확인 다이얼로그	`@radix-ui/react-alert-dialog`
`Tabs`	탭 UI	`@radix-ui/react-tabs`
`Avatar`	아바타/프로필 이미지	`@radix-ui/react-avatar`
`Tooltip`	툴팁	`@radix-ui/react-tooltip`
`Progress`	진행률 표시	`@radix-ui/react-progress`
`Accordion`	아코디언	`@radix-ui/react-accordion`

shadcn-form (폼 컴포넌트)

컴포넌트	설명	의존성
`Input`	텍스트 입력	-
`Textarea`	다줄 텍스트 입력	-
`Checkbox`	체크박스	`@radix-ui/react-checkbox`
`RadioGroup`	라디오 버튼 그룹	`@radix-ui/react-radio-group`
`Slider`	슬라이더	`@radix-ui/react-slider`
`Switch`	토글 스위치	`@radix-ui/react-switch`
`Select`	드롭다운 선택	`@radix-ui/react-select`
`Form`	react-hook-form 통합	`react-hook-form`
`Label`	폼 레이블	`@radix-ui/react-label`
`InputOTP`	OTP 입력	`input-otp`

shadcn-overlay (오버레이 컴포넌트)

컴포넌트	설명	의존성
`Sheet`	슬라이드 패널	`@radix-ui/react-dialog`
`Drawer`	드로어	`vaul`
`Popover`	팝오버	`@radix-ui/react-popover`
`HoverCard`	호버 카드	`@radix-ui/react-hover-card`
`Command`	커맨드 팔레트	`cmdk`
`ContextMenu`	컨텍스트 메뉴	`@radix-ui/react-context-menu`

shadcn-nav (네비게이션 컴포넌트)

컴포넌트	설명	의존성
`NavigationMenu`	네비게이션 메뉴	`@radix-ui/react-navigation-menu`
`Menubar`	메뉴바	`@radix-ui/react-menubar`
`Breadcrumb`	브레드크럼	`@radix-ui/react-slot`
`Pagination`	페이지네이션	-
`DropdownMenu`	드롭다운 메뉴	`@radix-ui/react-dropdown-menu`

shadcn-data (데이터 표시 컴포넌트)

컴포넌트	설명	의존성
`Table`	테이블	-
`Card`	카드	-
`Badge`	뱃지	-
`Skeleton`	로딩 스켈레톤	-
`ScrollArea`	스크롤 영역	`@radix-ui/react-scroll-area`
`Separator`	구분선	`@radix-ui/react-separator`
`Resizable`	리사이즈 가능 패널	`react-resizable-panels`
`Collapsible`	접기/펼치기	`@radix-ui/react-collapsible`

shadcn-misc (기타 컴포넌트)

컴포넌트	설명	의존성
`Toggle`	토글 버튼	`@radix-ui/react-toggle`
`ToggleGroup`	토글 그룹	`@radix-ui/react-toggle-group`
`AspectRatio`	비율 유지 컨테이너	`@radix-ui/react-aspect-ratio`
`Calendar`	달력	`react-day-picker`
`Carousel`	캐러셀	`embla-carousel-react`
`Sonner`	토스트 알림	`sonner`

interactive (인터랙티브 컴포넌트)

출처: silvercare-master | 추출일: 2026-02-15

컴포넌트	설명	의존성
`ImageUpload`	드래그앤드롭 이미지 업로더 (프리뷰, 진행률, 업로드 함수 주입)	`lucide-react`
`ImageCropper`	이미지 크롭 모달 (비율 설정, 줌, WebP 출력)	`react-easy-crop`, `lucide-react`

mobile (모바일 전용 컴포넌트)

출처: silvercare-master | 추출일: 2026-02-15

컴포넌트	설명	의존성
`PullToRefresh`	풀투리프레시 (터치 제스처, 감속, 인디케이터)	`lucide-react`
`SwipeableListItem`	스와이프 액션 리스트 아이템 (터치+마우스, 프리셋 액션)	`lucide-react`

02-hooks (React 커스텀 훅)

파일	설명	출처
`useFavorite.ts`	찜하기/즐겨찾기 토글 훅 (낙관적 업데이트 버전 포함)	260111-tiny-house
`useDebounce.ts`	디바운스 훅	silvercare-master
`useFocusTrap.ts`	포커스 트랩 훅 (모달/다이얼로그용)	-
`useGeolocation.ts`	위치 정보 훅	silvercare-master
`useInfiniteScroll.ts`	무한 스크롤 훅	silvercare-master
`useKeyboardShortcuts.ts`	키보드 단축키 훅	-
`useMobile.ts`	모바일 감지 훅	kcsi-smpa
`useOnlineStatus.ts`	온라인 상태 감지 훅	silvercare-master
`usePagination.ts`	페이지네이션 상태 훅	kcsi-smpa
`usePasswordAttempt.ts`	비밀번호 시도 제한 훅	-
`useTheme.ts`	테마 전환 훅	silvercare-master
`useToast.ts`	토스트 알림 훅	shadcn/ui
`useCountUp.ts`	숫자 카운트업 애니메이션 (requestAnimationFrame)	silvercare-master
`useInView.ts`	IntersectionObserver 뷰포트 진입 감지 (1회)	silvercare-master
`useFileUpload.ts`	범용 파일 업로드 (업로드 함수 주입, 검증, 진행률)	silvercare-master
`useImageUpload.ts`	이미지 업로드 (업로드 함수 주입, 검증, 진행률)	silvercare-master
`useAutoSave.ts`	자동 저장 (변경 감지, 간격 설정, 수동 saveNow)	legal-tech-app
`useUnsavedChangesWarning.ts`	미저장 변경사항 이탈 경고 (beforeunload)	legal-tech-app

03-utils (유틸리티 함수)

파일	설명	출처
`a11y.ts`	접근성 유틸리티	-
`cn.ts`	Tailwind CSS 클래스 병합	monet-registry-main
`performance.ts`	성능 측정 유틸리티	-
`slug.ts`	URL slug 생성 (generateSlug, isValidSlug)	260111-tiny-house
`truncate.ts`	텍스트 자르기 (truncate, truncateWords, truncateMiddle)	260111-tiny-house
`url.ts`	URL 관련 유틸리티	-
`converters/area.ts`	면적 단위 변환 (sqFt, sqM, pyeong)	260111-tiny-house
`crypto/file-encryption.ts`	파일 암호화/복호화	-
`crypto/memo-encryption.ts`	메모 암호화/복호화	-
`export/csv.ts`	CSV 내보내기 유틸리티	-
`formatters/index.ts`	포맷팅 유틸 (가격, 평점, 시간, 이름 마스킹, 전화번호)	silvercare-master
`formatters/currency.ts`	국제화 통화 포맷팅 (formatCurrency, formatCurrencyRange)	260111-tiny-house
`geo/distance.ts`	거리 계산 유틸리티	-
`geo/validation.ts`	위치 정보 검증	-
`validators/password.ts`	비밀번호 검증 유틸리티	-
`sanitize.ts`	HTML 살균 (sanitizeHtml, sanitizeEmailHtml, escapeForTemplate)	silvercare-master
`text-analysis.ts`	한국어 텍스트 분석 (토큰화, 불용어 필터, 단어 빈도)	kcsi-smpa
`chart-utils.ts`	차트/HTML 요소 → PNG 이미지 변환/다운로드 (html2canvas)	kcsi-smpa
`anonymous-names.ts`	익명 한국어 이름 생성기 (200개, 랜덤/해시/인덱스)	kcsi-smpa
`export/excel.ts`	범용 Excel 내보내기 (다중 시트, 자동 컬럼 너비, xlsx)	kcsi-smpa
`export/pdf.ts`	범용 PDF 리포트 생성 (jsPDF + autotable)	kcsi-smpa
`export/hwpx.ts`	HWPX (한글) 문서 생성 빌더 (JSZip 기반)	kcsi-smpa
`errors.ts`	범용 에러 핸들링 (AppError, ValidationError, wrapError, ErrorHandlers)	legal-tech-app
`api-client.ts`	Type-safe API Client (토큰 자동 첨부, 401 갱신 재시도, CRUD 헬퍼)	silvercare-master
`retry-policy.ts`	재시도 정책 (지수 백오프, 커스텀 판별, 프리셋 API/DB)	silvercare-master

03-utils/browser-stealth (스텔스 브라우저 자동화)

출처: PleasePrompto/notebooklm-mcp | 추출일: 2026-03-18 의존성: 없음 (순수 TypeScript)

사람처럼 자연스러운 브라우저 자동화를 위한 유틸리티.

파일	설명
`types.ts`	공유 타입 (Point, BezierMouseOptions, GaussianDelayOptions 등)
`bezier-mouse.ts`	Bezier 커브 마우스 이동 경로 생성 (제어점 랜덤화, jitter)
`gaussian-delay.ts`	Gaussian 분포 딜레이 (Box-Muller 변환, sleep)
`typo-simulator.ts`	타이포 시뮬레이션 AsyncGenerator (QWERTY 인접키, 오타→수정)
`dom-stability.ts`	해시 기반 DOM 안정성 감지 (djb2, 연속 일치 판정)
`index.ts`	배럴 export

03-utils/web3 (Web3 상수/타입)

파일	설명	비고
`types.ts`	Web3 결제 관련 타입 정의 (ChainId, TokenSymbol, PaymentRequest 등)	레퍼런스 코드
`constants.ts`	체인별 RPC URL, USDC/USDT 토큰 주소, ERC20 ABI	레퍼런스 코드

02-hooks/web3 (Web3 React 훅)

파일	설명	비고
`useWallet.ts`	MetaMask 지갑 연결/해제/체인 전환 훅	레퍼런스 코드
`useUSDCPayment.ts`	USDC/USDT 전송 및 잔액 조회 훅	레퍼런스 코드

01-ui-components/web3 (Web3 UI 컴포넌트)

파일	설명	비고
`CryptoPayment.tsx`	스테이블코인 결제 완전 UI 컴포넌트	레퍼런스 코드

08-services/web3 (Web3 백엔드 서비스)

파일	설명	비고
`verify-payment.ts`	트랜잭션 해시로 결제 검증 (백엔드용)	레퍼런스 코드

Web3 결제 사용 가이드

의존성

# 클라이언트 훅/컴포넌트는 별도 의존성 없음 (window.ethereum 직접 사용)
# 서버 검증은 fetch만 사용

지원 체인

체인	ChainId	비고
Ethereum	1	가스비 높음
Polygon	137	권장 (낮은 가스비)
Arbitrum	42161	L2
Optimism	10	L2
Base	8453	L2

사용 예시

// 클라이언트
import { CryptoPayment } from '@/components/web3/CryptoPayment';

<CryptoPayment
  amount="100.00"
  recipientAddress="0x..."
  supportedChains={[137, 42161]}
  onSuccess={(result) => {
    // 백엔드에 txHash 전송하여 검증
    fetch('/api/verify-payment', {
      method: 'POST',
      body: JSON.stringify({ txHash: result.txHash }),
    });
  }}
/>

// 서버 (Next.js API Route)
import { verifyPayment } from '@/lib/web3/verify-payment';

const result = await verifyPayment({
  txHash: body.txHash,
  expectedAmount: '100.00',
  expectedRecipient: process.env.PAYMENT_ADDRESS,
  expectedToken: 'USDC',
  chainId: 137,
});

추가 카테고리

04-supabase-patterns (Supabase 패턴)

파일	설명	비고
`prisma.ts`	Prisma + Supabase 통합 패턴	-

05-auth-rbac (인증/권한 패턴)

파일	설명	비고
`mfa.ts`	MFA 다중 인증 패턴	-
`rbac-permissions.ts`	역할 기반 접근 제어	-
`user.ts`	사용자 인증 패턴	-

edge-jwt (Edge 호환 JWT 인증)

출처: dokiwiki-main | 추출일: 2026-02-16 의존성: 없음 (Web Crypto API만 사용, Edge Runtime 호환)

파일	설명
`auth-types.ts`	PublicUser, JWTPayload, Session, TokenPair 인터페이스
`jwt.ts`	JWT 생성/검증 (HMAC-SHA256), 토큰 페어, 쿠키 헬퍼, Bearer 추출
`password.ts`	PBKDF2-SHA256 비밀번호 해싱, timing-safe 비교, 이메일/비밀번호 검증

06-api-middleware (API 미들웨어)

파일	설명	비고
`cache-tags.ts`	캐시 태그 관리	-
`errors.ts`	API 에러 핸들링	monet-registry-main
`rate-limit.ts`	레이트 리미팅	-
`upstash-rate-limit.ts`	Upstash 레이트 리미팅	-
`api-keys/index.ts`	API 키 관리	-
`api-keys/middleware.ts`	API 키 미들웨어	-
`bff/backend-client.ts`	BFF 백엔드 클라이언트	-
`security/waf.ts`	WAF 보안 패턴	-
`session/index.ts`	세션 관리	-
`api-response.ts`	통일 API 응답 헬퍼 (apiSuccess, apiError, ApiErrors 단축)	silvercare-master

middleware-system (범용 미들웨어 시스템)

출처: dokiwiki-main | 추출일: 2026-02-16 의존성: 없음 (api-rate-limit.ts만 next/server 필요)

파일	설명
`types.ts`	GenericRequest/Response, MiddlewareFn 타입, extractClientIp (Vercel/CF/프록시)
`kv-store.ts`	KVStore 인터페이스 + MemoryKVStore (TTL 자동 만료, Redis 교체 가능)
`rate-limit.ts`	Rate Limiting + 실패 시도 추적/차단 (로그인 보호)
`api-rate-limit.ts`	Next.js API Route 원라인 적용 + 프리셋 (AUTH_STRICT, STANDARD 등)
`request-logger.ts`	요청 로깅 (시작/종료 측정, 경로 제외, 커스텀 transport)
`compose.ts`	미들웨어 합성 (composeMiddleware) + 조건부 실행 (when)

07-contexts (React 컨텍스트)

파일	설명	비고
`DarkModeProvider.tsx`	다크모드 컨텍스트	-
`QueryProvider.tsx`	React Query 프로바이더	-

08-services (서비스 레이어)

파일	설명	비고
`singleton-service-pattern.ts`	싱글톤 서비스 패턴	-
`audit-logger/index.ts`	감사 로깅 서비스	-
`storage/index.ts`	파일 스토리지 서비스	-
`cloudinary/`	Cloudinary 이미지 CDN (업로드, 압축, URL 최적화)	silvercare-master

10-stripe-patterns (Stripe SaaS 구독 결제)

출처: secure-vault-master + monet-registry-main | 추출일: 2026-02-16

config (설정)

파일	설명	의존성
`stripe-server.ts`	서버 클라이언트 (지연 초기화), Price ID 매핑, 플랜 정보	`stripe`
`stripe-client.ts`	브라우저 Stripe.js 로더	`@stripe/stripe-js`

api (API 라우트 - Next.js App Router)

파일	엔드포인트	설명
`checkout.ts`	`POST /api/billing/checkout`	Checkout 세션 생성 (14일 무료체험, 프로모션 코드)
`webhook.ts`	`POST /api/webhooks/stripe`	Webhook 핸들러 (구독 생성/변경/취소, 결제 성공/실패)
`portal.ts`	`POST /api/billing/portal`	Customer Portal 세션
`change-plan.ts`	`POST /api/billing/change-plan`	플랜 업/다운그레이드 (비례정산)
`preview-change.ts`	`POST /api/billing/preview-change`	비례정산 미리보기
`payment-method.ts`	`GET /api/billing/payment-method`	결제수단 조회 (카드 브랜드/last4)
`invoices.ts`	`GET /api/billing/invoices`	인보이스 이력 (PDF URL 포함)

components (UI 컴포넌트)

파일	설명	의존성
`pricing-cards.tsx`	가격표 카드 (월/연 토글, 현재 플랜 표시, 업/다운 자동 판별)	shadcn/ui, lucide-react
`plan-change-dialog.tsx`	플랜 변경 다이얼로그 (비례정산 미리보기, 확인/취소)	shadcn/ui, lucide-react

schema (DB 스키마)

파일	설명	비고
`supabase-saas.sql`	plans + subscriptions + usage_metrics + audit_logs + 트리거/RPC	Supabase SQL Editor에서 실행

02-hooks 추가 훅 (GitHub 커뮤니티)

출처: usehooks-ts, @uidotdev/usehooks, ahooks, @mantine/hooks, react-use 추출일: 2026-02-16

Tier 1 — 필수

파일	설명
`useLocalStorage.ts`	localStorage React state (SSR 안전, 탭 간 동기화)
`useSessionStorage.ts`	sessionStorage React state
`useMediaQuery.ts`	CSS 미디어쿼리 반응형 감지
`useEventListener.ts`	DOM 이벤트 리스너 자동 등록/해제
`useClickOutside.ts`	요소 바깥 클릭 감지
`useInterval.ts`	setInterval 래퍼 (자동 cleanup)
`useTimeout.ts`	setTimeout 래퍼 (reset/clear 제어)
`useToggle.ts`	boolean 상태 토글
`useCopyToClipboard.ts`	클립보드 복사 + 상태 추적
`usePrevious.ts`	이전 렌더 값 추적

Tier 2 — 매우 유용

파일	설명
`useWindowSize.ts`	윈도우 크기 추적 (debounce 포함)
`useScrollLock.ts`	body 스크롤 잠금 (모달용)
`useHover.ts`	요소 hover 상태 감지
`useLongPress.ts`	길게 누르기 제스처 감지
`useDocumentTitle.ts`	문서 제목 동적 변경
`useScript.ts`	외부 스크립트 동적 로딩
`useIdle.ts`	사용자 비활동 감지
`useMouse.ts`	마우스 위치 추적 (글로벌 + 요소 기준)
`useWindowScroll.ts`	윈도우 스크롤 위치 추적 + 제어
`useCounter.ts`	숫자 상태 (increment/decrement/min/max)

Tier 3 — 데이터 구조

파일	설명
`useMap.ts`	Map 자료구조 상태 관리
`useSet.ts`	Set 자료구조 상태 관리
`useQueue.ts`	FIFO 큐 상태 관리
`useList.ts`	배열 상태 (push/remove/update/swap/move)
`useIsFirstRender.ts`	첫 렌더 여부 감지
`useStep.ts`	스텝 진행 관리 (위자드 UI)
`useCookie.ts`	쿠키 read/write/delete
`useVisibilityChange.ts`	페이지 가시성 변경 감지 (탭 전환)

03-utils 추가 유틸 (GitHub 커뮤니티)

추출일: 2026-02-16

파일	설명	의존성
`type-guards.ts`	타입 가드 15개 (isString, isObject, isEmpty 등)	없음
`deep.ts`	딥 객체 유틸 (deepClone, deepEqual, deepMerge, shake, crush, construct)	없음
`promise.ts`	Promise 유틸 (pLimit, pMap, pRetry, tryit, defer, parallel)	없음
`functional.ts`	함수형 유틸 (pipe, compose, partial, once, negate)	없음
`id.ts`	ID 생성 (nanoid, cuid, uuid)	없음
`math.ts`	수학/통계 (mean, median, mode, variance, percentile 등)	없음
`color.ts`	색상 유틸 (hexToRgb, lighten, darken, contrast 등)	없음
`event-emitter.ts`	이벤트 이미터 (~200B, 와일드카드 지원)	없음
`validation-schemas.ts`	Zod 공통 스키마 (email, url, phone, password, pagination)	zod
`array.ts` (확장)	+7 함수 (intersects, diff, fork, toggle, select, shift, zipToObject)	없음
`date.ts` (확장)	+8 함수 (addBusinessDays, startOf, endOf, isWeekend, isBefore 등)	없음

03-utils/types (TypeScript 타입 유틸)

파일	설명
`type-helpers.ts`	DeepPartial, Prettify, StrictOmit, RequireAtLeastOne 등 12개
`branded-types.ts`	브랜드 타입 (UserId, Email 등 명목적 타입)
`discriminated-unions.ts`	판별 유니온 + 패턴 매칭 + Result 타입

01-ui-components/error-boundary (Error Boundary)

출처: GitHub-커뮤니티 | 추출일: 2026-02-16

파일	설명
`ErrorBoundary.tsx`	클래스 기반 Error Boundary (resetKeys 자동 리셋)
`ErrorFallback.tsx`	재사용 가능 에러 폴백 UI (아이콘, 상세 토글)
`useErrorBoundary.ts`	명령형 에러 전달 훅 (이벤트 핸들러/비동기 코드용)

11-state-patterns (상태관리 패턴)

출처: GitHub-커뮤니티 | 추출일: 2026-02-16

zustand

파일	설명	의존성
`slice-pattern.ts`	모듈러 슬라이스 패턴 + combineSlices 헬퍼	zustand
`persist-middleware.ts`	선택적 영속화 + 만료 스토리지	zustand
`immer-middleware.ts`	Immer 불변 업데이트 + deepUpdate 헬퍼	zustand, immer

react-query

파일	설명	의존성
`query-key-factory.ts`	쿼리 키 팩토리 + CRUD 프리셋	@tanstack/react-query
`optimistic-updates.ts`	낙관적 업데이트/롤백 헬퍼	@tanstack/react-query
`infinite-query.ts`	무한 쿼리 + 페이지네이션 헬퍼	@tanstack/react-query

jotai

파일	설명	의존성
`atom-patterns.ts`	기본/파생/비동기/스토리지 atom 패턴	jotai

12-nextjs-patterns (Next.js App Router 패턴)

출처: GitHub-커뮤니티 | 추출일: 2026-02-16

파일	설명	의존성
`server-actions/form-action.ts`	Server Action + Zod 검증 + useActionState	next, zod
`server-actions/authenticated-action.ts`	인증 필수 Server Action 팩토리	next
`server-actions/optimistic-action.ts`	낙관적 UI 업데이트 + useOptimistic	react, next
`route-handlers/api-helpers.ts`	표준 API 응답 포맷 + 에러 핸들링 래퍼	next, zod
`streaming/suspense-pattern.tsx`	AsyncBoundary (Suspense + Error Boundary)	react
`rsc/server-client-composition.tsx`	Server/Client 합성 패턴 + 직렬화 헬퍼	react
`middleware/auth-middleware.ts`	경로 기반 인증 미들웨어	next

13-testing-patterns (테스팅 패턴)

출처: GitHub-커뮤니티 | 추출일: 2026-02-16

파일	설명	의존성
`vitest/vitest.config.ts`	Vitest 기본 설정 (globals, happy-dom, 커버리지)	vitest, @vitejs/plugin-react
`testing-library/custom-render.tsx`	Provider 래핑 커스텀 render	@testing-library/react, @tanstack/react-query
`msw/handlers.ts`	MSW 요청 핸들러 + CRUD 팩토리	msw
`msw/server-setup.ts`	MSW Node 서버 설정 + 생명주기 관리	msw
`playwright/base-page.ts`	Page Object 베이스 클래스	@playwright/test
`playwright/page-fixtures.ts`	커스텀 Fixture 패턴 + 인증 상태	@playwright/test

14-mcp-catalog (MCP 서버 카탈로그)

추가일: 2026-03-07

Claude Code에서 사용 가능한 MCP 서버 메타데이터 레지스트리. 각 서버의 설정 스니펫, 제공 도구, 사용 사례를 표준화된 형식으로 관리.

카테고리	서버 수	서버
browser	2	Playwright, Puppeteer
search	2	Tavily, Brave Search
database	3	PostgreSQL, Supabase, SQLite
filesystem	1	Filesystem
memory	1	Memory
devtools	2	GitHub, Sentry
communication	2	Slack, Gmail
cloud	1	Cloudflare

상세: 14-mcp-catalog/README.md

15-crawler-patterns (웹 크롤링 파이프라인 패턴)

출처: galaxy-con | 추출일: 2026-03-08

멀티소스 웹 크롤링 5단계 파이프라인: 수집 → 정규화 → 중복제거 → 검증 → 저장. 소스 어댑터 패턴, 교차 소스 중복제거(5계층), 의존성 주입(소스팩토리/DB Writer) 제공.

핵심 파일

파일	설명	의존성
`types.ts`	공통 타입 (RawItem, NormalizedItem, CrawlResult, SourceAdapter)	없음
`config.ts`	크롤러 설정 + 소스별 설정 인터페이스	없음
`cli.ts`	CLI 진입점 (인수 파싱, 상태 출력, 파이프라인 실행)	run-pipeline, config
`sources/base-source.ts`	HTML 크롤링용 소스 어댑터 추상 클래스	types, config
`sources/base-api-source.ts`	REST API용 소스 어댑터 (Rate Limit + Retry 내장)	types, config
`pipeline/fetcher.ts`	HTTP 클라이언트 (GET/POST, Rate Limit + Retry)	config
`pipeline/korean-text.ts`	한국어 텍스트 파서 (날짜, 상금, 제목, HTML, 상태)	없음
`pipeline/global-text.ts`	영어 텍스트 파서 (날짜, 상금, 통화 감지)	없음
`pipeline/currency-converter.ts`	환율 변환기 (고정+API, 대상 통화 설정 가능)	없음
`pipeline/normalizer.ts`	Raw→Normalized 변환 (슬러그/카테고리/자격 함수 주입)	korean-text, global-text, currency-converter
`pipeline/deduplicator.ts`	배치 내 중복제거 + 유사 제목 비교 (Dice 계수)	korean-text
`pipeline/cross-source-dedup.ts`	교차 소스 5계층 중복제거 + 충돌 병합	korean-text, deduplicator
`pipeline/completeness.ts`	데이터 완성도 점수 (필드별 가중치)	types
`pipeline/validator.ts`	Zod 스키마 검증 (카테고리 목록 주입 가능)	zod, types
`pipeline/run-pipeline.ts`	5단계 파이프라인 엔진 (소스팩토리/저장함수 주입)	normalizer, deduplicator, validator
`storage/db-writer.ts`	DB 저장 추상 레이어 + InMemoryDbWriter	types

상세: 15-crawler-patterns/README.md

16-algorithm-engines (알고리즘 엔진 + 캔버스 시각화)

출처: galaxy-con | 추출일: 2026-03-08

물리 시뮬레이션 엔진(순수 TypeScript)과 Canvas/WebGL 기반 인터랙티브 시각화 React 컴포넌트.

physics (물리 엔진)

파일	설명	의존성
`boids.ts`	Boids 군집 알고리즘 (분리·정렬·결합 + 마우스 끌림)	없음
`n-body.ts`	N-Body 은하계 시뮬레이션 (중력·궤도·줌/팬·호버/클릭)	없음

canvas (React 캔버스 컴포넌트)

파일	설명	의존성
`BoidsCanvas.tsx`	Boids 군집 시각화 (포식자 회피, 과밀집 비산, 그룹 색상)	React
`BoidsBackground.tsx`	전체 화면 Boids 배경 효과	React, `physics/boids`
`GalaxyCanvas.tsx`	데이터 기반 은하계 인터랙티브 시각화	React, `physics/n-body`
`MandelbrotCanvas.tsx`	만델브로 프랙탈 자동 줌인 (WebGL)	React, WebGL
`FluidCanvas.tsx`	나비에-스토크스 유체 역학 (WebGL 2)	React, WebGL 2
`JuliaPreview.tsx`	줄리아 집합 프리뷰/아이콘 (Canvas 2D, 메모이즈)	React

상세: 16-algorithm-engines/README.md

17-verification-patterns (엔티티 신뢰도 검증)

출처: galaxy-con | 추출일: 2026-03-08

Trust Score(가중치 기반 0~100 신뢰도 점수) 산출 + URL 안전성 검증(URLhaus + VirusTotal) 통합 패턴.

파일	설명	의존성
`types.ts`	공통 타입 (TrustSignals, VerificationInput, VerificationResult 등)	없음
`trust-score.ts`	가중치 기반 Trust Score 계산 엔진 (설정 가능한 가중치/패널티)	없음
`url-verification.ts`	URLhaus + VirusTotal 기반 URL 안전성 검증	fetch API
`index.ts`	통합 검증 오케스트레이터 + re-exports	없음

환경변수: VIRUSTOTAL_API_KEY (선택)

상세: 17-verification-patterns/README.md

02-reusable-code — 범용 재사용 코드 라이브러리

02-reusable-code — 범용 재사용 코드 라이브러리

개요

3계층 모델에서의 위치

code에 넣는 것

code에 넣지 않는 것

폴더 구조

호환성

사용 전 설정

1. 의존성 설치

2. 경로 별칭 설정 (tsconfig.json)

3. cn 유틸리티 복사

출처 기록

카테고리별 파일 목록

01-ui-components/_shared (공통 유틸)

01-ui-components/feedback (상태 표시 컴포넌트)

01-ui-components/lib (유틸리티)

01-ui-components/shadcn-* (shadcn/ui 컴포넌트)

shadcn-core (핵심 컴포넌트)

shadcn-form (폼 컴포넌트)

shadcn-overlay (오버레이 컴포넌트)

shadcn-nav (네비게이션 컴포넌트)

shadcn-data (데이터 표시 컴포넌트)

shadcn-misc (기타 컴포넌트)

interactive (인터랙티브 컴포넌트)

mobile (모바일 전용 컴포넌트)

02-hooks (React 커스텀 훅)

03-utils (유틸리티 함수)

03-utils/browser-stealth (스텔스 브라우저 자동화)

03-utils/web3 (Web3 상수/타입)

02-hooks/web3 (Web3 React 훅)

01-ui-components/web3 (Web3 UI 컴포넌트)

08-services/web3 (Web3 백엔드 서비스)

Web3 결제 사용 가이드

의존성

지원 체인

사용 예시

추가 카테고리

04-supabase-patterns (Supabase 패턴)

05-auth-rbac (인증/권한 패턴)

edge-jwt (Edge 호환 JWT 인증)

06-api-middleware (API 미들웨어)

middleware-system (범용 미들웨어 시스템)

07-contexts (React 컨텍스트)

08-services (서비스 레이어)

10-stripe-patterns (Stripe SaaS 구독 결제)

config (설정)

api (API 라우트 - Next.js App Router)

components (UI 컴포넌트)

schema (DB 스키마)

02-hooks 추가 훅 (GitHub 커뮤니티)

Tier 1 — 필수

Tier 2 — 매우 유용

Tier 3 — 데이터 구조

03-utils 추가 유틸 (GitHub 커뮤니티)

03-utils/types (TypeScript 타입 유틸)

01-ui-components/error-boundary (Error Boundary)

11-state-patterns (상태관리 패턴)

zustand

react-query

jotai

12-nextjs-patterns (Next.js App Router 패턴)

13-testing-patterns (테스팅 패턴)

14-mcp-catalog (MCP 서버 카탈로그)

15-crawler-patterns (웹 크롤링 파이프라인 패턴)

핵심 파일

16-algorithm-engines (알고리즘 엔진 + 캔버스 시각화)

physics (물리 엔진)

canvas (React 캔버스 컴포넌트)

17-verification-patterns (엔티티 신뢰도 검증)

관련 문서