Antigravity Agent
174 lines
4.4 KiB
Markdown
174 lines
4.4 KiB
Markdown
---
|
|
id: ts-tsconfig-strategy
|
|
title: tsconfig 전략 — strict / paths / project references
|
|
category: Coding
|
|
status: draft
|
|
source_trust_level: B
|
|
verification_status: conceptual
|
|
created_at: 2026-05-09
|
|
updated_at: 2026-05-09
|
|
tags: [typescript, tsconfig, build, vibe-coding]
|
|
tech_stack: { language: "TypeScript", applicable_to: ["Backend", "Frontend"] }
|
|
applied_in: []
|
|
aliases: [tsconfig.json, strict, isolatedModules, project references, paths]
|
|
---
|
|
|
|
# tsconfig 전략
|
|
|
|
> 디폴트로 켜야 할 것: **strict / noUncheckedIndexedAccess / exactOptionalPropertyTypes**. 모노레포면 project references. 빌드 도구가 type-check 안 해줌 → `tsc --noEmit` CI 필수.
|
|
|
|
## 📖 핵심 개념
|
|
- `strict`: 7개 옵션 묶음.
|
|
- Compiler vs type-checker: bundler (esbuild/swc) 가 컴파일, tsc 는 검사 전담.
|
|
- Project references: 큰 monorepo 의 점진 빌드.
|
|
- Module 모드: `node16`/`nodenext` 가 ESM/CJS 정확.
|
|
|
|
## 💻 코드 패턴
|
|
|
|
### 시작 base
|
|
```jsonc
|
|
// tsconfig.base.json
|
|
{
|
|
"compilerOptions": {
|
|
"target": "ES2022",
|
|
"module": "NodeNext",
|
|
"moduleResolution": "NodeNext",
|
|
"lib": ["ES2023", "DOM"],
|
|
"strict": true,
|
|
"noUncheckedIndexedAccess": true,
|
|
"noImplicitOverride": true,
|
|
"exactOptionalPropertyTypes": true,
|
|
"noFallthroughCasesInSwitch": true,
|
|
"noPropertyAccessFromIndexSignature": true,
|
|
"isolatedModules": true,
|
|
"esModuleInterop": true,
|
|
"skipLibCheck": true,
|
|
"forceConsistentCasingInFileNames": true,
|
|
"verbatimModuleSyntax": true,
|
|
"resolveJsonModule": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### App 별 override
|
|
```jsonc
|
|
// apps/api/tsconfig.json
|
|
{
|
|
"extends": "../../tsconfig.base.json",
|
|
"compilerOptions": {
|
|
"outDir": "dist",
|
|
"rootDir": "src",
|
|
"types": ["node"]
|
|
},
|
|
"include": ["src/**/*"],
|
|
"exclude": ["dist", "**/*.test.ts"]
|
|
}
|
|
```
|
|
|
|
### Path alias
|
|
```jsonc
|
|
{
|
|
"compilerOptions": {
|
|
"baseUrl": ".",
|
|
"paths": {
|
|
"@/*": ["src/*"],
|
|
"@shared/*": ["../shared/src/*"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
런타임 호환: tsx / vite / Next.js 자동. Node 직접 실행 시 `tsx` 또는 `tsconfig-paths/register`.
|
|
|
|
### Project references (monorepo)
|
|
```jsonc
|
|
// root tsconfig.json
|
|
{
|
|
"files": [],
|
|
"references": [
|
|
{ "path": "packages/shared" },
|
|
{ "path": "apps/api" },
|
|
{ "path": "apps/web" }
|
|
]
|
|
}
|
|
|
|
// packages/shared/tsconfig.json
|
|
{
|
|
"compilerOptions": { "composite": true, "declaration": true, "outDir": "dist" },
|
|
"include": ["src/**/*"]
|
|
}
|
|
|
|
// apps/api/tsconfig.json (참조)
|
|
{
|
|
"references": [{ "path": "../../packages/shared" }]
|
|
}
|
|
```
|
|
|
|
```bash
|
|
tsc --build # 모두 점진
|
|
tsc --build --watch # watch
|
|
tsc --build --clean # 정리
|
|
```
|
|
|
|
### Type-only import (verbatimModuleSyntax)
|
|
```ts
|
|
import { type User, getUser } from './user';
|
|
// 컴파일 결과: type User 는 erased, 안전
|
|
```
|
|
|
|
### CI type-check (bundle 따로)
|
|
```yaml
|
|
- run: tsc --noEmit # type 만 검사
|
|
- run: vite build # bundle (esbuild/swc)
|
|
```
|
|
|
|
bundler 가 type 무시 — 별도 step.
|
|
|
|
### Browser vs Node 분리
|
|
```jsonc
|
|
// web tsconfig
|
|
"lib": ["ES2023", "DOM", "DOM.Iterable"]
|
|
"types": [] // node types 빼기
|
|
|
|
// node tsconfig
|
|
"lib": ["ES2023"]
|
|
"types": ["node"]
|
|
```
|
|
|
|
### Decorator (Nest 등)
|
|
```jsonc
|
|
"experimentalDecorators": true,
|
|
"emitDecoratorMetadata": true
|
|
```
|
|
|
|
또는 TS 5.0+ stage-3 decorators.
|
|
|
|
## 🤔 의사결정 기준
|
|
| 상황 | 옵션 |
|
|
|---|---|
|
|
| 새 프로젝트 | strict + noUncheckedIndexedAccess |
|
|
| 점진 마이그레이션 | strict 부분 켜기 (`strictNullChecks` 부터) |
|
|
| ESM Node 18+ | `module: nodenext` |
|
|
| Vite/Next | `moduleResolution: bundler` |
|
|
| Monorepo 큰 | project references |
|
|
| Library 배포 | `composite: true`, `declaration: true` |
|
|
|
|
## ❌ 안티패턴
|
|
- **strict false 그대로**: 의미 절반 잃음.
|
|
- **`@ts-ignore` 남발**: 차라리 `as` + 주석.
|
|
- **`any` 도배**: `unknown` + 좁히기.
|
|
- **path alias 만 — runtime resolver X**: import 깨짐.
|
|
- **`tsc` 빌드 + bundler 빌드 둘 다**: 한쪽 only. tsc=check, bundler=build.
|
|
- **`skipLibCheck: false` 항상**: node_modules 타입 깨지면 빌드 fail. 기본 true.
|
|
- **`isolatedModules: false`**: esbuild/swc 가 일부 패턴 못 컴파일.
|
|
|
|
## 🤖 LLM 활용 힌트
|
|
- strict + noUncheckedIndexedAccess + exactOptionalPropertyTypes 항상.
|
|
- bundler 컴파일 + tsc 검사 분리.
|
|
- monorepo = project references.
|
|
|
|
## 🔗 관련 문서
|
|
- [[TS_Build_Bundler_Patterns]]
|
|
- [[TS_Monorepo_Patterns]]
|
|
- [[JS_Module_System_ESM_CJS]]
|