[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,204 @@
|
||||
---
|
||||
id: ts-monorepo-patterns
|
||||
title: TS Monorepo — pnpm workspace / Turborepo / Nx
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [typescript, monorepo, pnpm, turborepo, vibe-coding]
|
||||
tech_stack: { language: "TypeScript / pnpm", applicable_to: ["Backend", "Frontend"] }
|
||||
applied_in: []
|
||||
aliases: [pnpm workspace, Turborepo, Nx, project references, workspaces]
|
||||
---
|
||||
|
||||
# TS Monorepo
|
||||
|
||||
> 여러 패키지 한 repo. **pnpm workspace + TS project references + Turborepo (cache) 가 표준 조합**. Nx 는 더 강력하지만 무겁다. shared 패키지 = source 그대로 import.
|
||||
|
||||
## 📖 핵심 개념
|
||||
- Workspace: pnpm/yarn/npm 의 다중 패키지 등록.
|
||||
- Hoisting: pnpm 은 strict (의도하지 않은 의존성 차단).
|
||||
- Project references: tsc 가 의존 graph 알고 점진 build.
|
||||
- Cache: Turbo/Nx 가 입력 hash 동일 시 결과 재사용.
|
||||
|
||||
## 💻 코드 패턴
|
||||
|
||||
### 폴더 구조
|
||||
```
|
||||
my-monorepo/
|
||||
package.json
|
||||
pnpm-workspace.yaml
|
||||
turbo.json
|
||||
tsconfig.base.json
|
||||
apps/
|
||||
api/ (Node)
|
||||
web/ (Next/Vite)
|
||||
packages/
|
||||
shared/ (TS lib)
|
||||
ui/ (React lib)
|
||||
config/ (tsconfig/eslint base)
|
||||
```
|
||||
|
||||
### pnpm workspace
|
||||
```yaml
|
||||
# pnpm-workspace.yaml
|
||||
packages:
|
||||
- 'apps/*'
|
||||
- 'packages/*'
|
||||
```
|
||||
|
||||
```jsonc
|
||||
// apps/api/package.json
|
||||
{
|
||||
"name": "@app/api",
|
||||
"dependencies": {
|
||||
"@app/shared": "workspace:*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Turborepo
|
||||
```json
|
||||
// turbo.json
|
||||
{
|
||||
"$schema": "https://turbo.build/schema.json",
|
||||
"tasks": {
|
||||
"build": {
|
||||
"dependsOn": ["^build"],
|
||||
"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
|
||||
},
|
||||
"lint": {},
|
||||
"typecheck": { "dependsOn": ["^build"] },
|
||||
"test": { "dependsOn": ["^build"] },
|
||||
"dev": { "cache": false, "persistent": true }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
turbo build --filter=@app/web...
|
||||
turbo dev --filter=@app/api
|
||||
```
|
||||
|
||||
### TS project references
|
||||
```jsonc
|
||||
// tsconfig.base.json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"strict": true,
|
||||
"isolatedModules": true,
|
||||
"composite": true,
|
||||
"declaration": true,
|
||||
"declarationMap": true,
|
||||
"incremental": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```jsonc
|
||||
// packages/shared/tsconfig.json
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"include": ["src/**/*"],
|
||||
"compilerOptions": { "outDir": "dist", "rootDir": "src" }
|
||||
}
|
||||
```
|
||||
|
||||
```jsonc
|
||||
// apps/api/tsconfig.json
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"references": [
|
||||
{ "path": "../../packages/shared" }
|
||||
],
|
||||
"include": ["src/**/*"]
|
||||
}
|
||||
```
|
||||
|
||||
### shared 패키지 — source 직접 export
|
||||
```jsonc
|
||||
// packages/shared/package.json
|
||||
{
|
||||
"name": "@app/shared",
|
||||
"main": "./src/index.ts",
|
||||
"types": "./src/index.ts",
|
||||
"exports": {
|
||||
".": "./src/index.ts"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
bundler/Vite/Next 는 monorepo 내부 패키지 source 직접 컴파일. dist 빌드 불필요.
|
||||
배포 패키지 (npm publish) 는 dist 빌드 필요.
|
||||
|
||||
### Tooling 공유
|
||||
```jsonc
|
||||
// packages/config/tsconfig.base.json (위와 동일)
|
||||
|
||||
// packages/config/eslint.cjs
|
||||
module.exports = {
|
||||
extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
|
||||
// ...
|
||||
};
|
||||
|
||||
// 다른 패키지에서
|
||||
{ "extends": "@app/config/tsconfig.base.json" }
|
||||
```
|
||||
|
||||
### Filter (특정 패키지만)
|
||||
```bash
|
||||
pnpm --filter @app/web add zod
|
||||
pnpm --filter @app/web build
|
||||
turbo build --filter=...[origin/main] # 변경된 것 + 의존
|
||||
```
|
||||
|
||||
### CI 캐시 (Turbo + GitHub Actions)
|
||||
```yaml
|
||||
- uses: actions/cache@v4
|
||||
with:
|
||||
path: .turbo
|
||||
key: turbo-${{ github.sha }}
|
||||
restore-keys: turbo-
|
||||
|
||||
- run: pnpm turbo build typecheck test --cache-dir=.turbo
|
||||
```
|
||||
|
||||
Remote cache (Vercel / self-hosted) 가 multi-machine 공유.
|
||||
|
||||
### Versioning + publish (Changesets)
|
||||
```bash
|
||||
pnpm changeset # add changeset
|
||||
pnpm changeset version # bump versions
|
||||
pnpm changeset publish
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
| 규모 | 도구 |
|
||||
|---|---|
|
||||
| 작은 (5 패키지) | pnpm workspace 만 |
|
||||
| 중간 | + Turborepo |
|
||||
| 큰 / 복잡 의존 | + Nx (codegen, generators) |
|
||||
| Polyglot (TS + Go + Python) | Bazel / Pants |
|
||||
| Library publish | + Changesets |
|
||||
| Type 정확 빌드 | + project references |
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **node_modules 매 패키지**: 디스크 / 시간 낭비. pnpm hoist.
|
||||
- **Symlink 안 씀 — copy 기반**: 변경이 다른 패키지 못 봄.
|
||||
- **Project references 없이 거대 단일 tsconfig**: tsc 매번 전부 검사.
|
||||
- **Shared 패키지 dist 빌드 강제 dev**: dev 부담. source export.
|
||||
- **Versioning 수동**: 망가짐. Changesets.
|
||||
- **CI 캐시 미사용**: 매번 5-10분.
|
||||
- **모든 패키지 한꺼번에 build**: filter 로 변경된 것만.
|
||||
|
||||
## 🤖 LLM 활용 힌트
|
||||
- pnpm + Turbo + Changesets + project references 4종 조합.
|
||||
- Source 직접 export (dev), dist (publish).
|
||||
- CI 는 변경 그래프 기반 filter.
|
||||
|
||||
## 🔗 관련 문서
|
||||
- [[TS_tsconfig_Strategy]]
|
||||
- [[TS_Build_Bundler_Patterns]]
|
||||
- [[DevOps_Monorepo_Patterns]]
|
||||
Reference in New Issue
Block a user