[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,172 @@
+---
+id: ts-build-bundler-patterns
+title: TS Build / Bundler — esbuild / tsup / Vite
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [typescript, bundler, build, esbuild, vibe-coding]
+tech_stack: { language: "TypeScript", applicable_to: ["Backend", "Frontend"] }
+applied_in: []
+aliases: [tsup, esbuild, swc, vite, rollup, bundler comparison]
+---
+
+# TS Build / Bundler
+
+> tsc 는 type-check, **번들/컴파일은 esbuild/swc/Rollup**. **Library = tsup, App backend = tsx (dev) + esbuild/swc (build), App frontend = Vite/Next**. Source map 항상.
+
+## 📖 핵심 개념
+- Compiler: TS → JS (esbuild/swc/tsc).
+- Bundler: 의존성 묶기 (esbuild/Rollup/Webpack).
+- DTS: `.d.ts` 생성 (tsc/api-extractor/rollup-plugin-dts).
+- Tree-shaking: 안 쓴 export 제거.
+
+## 💻 코드 패턴
+
+### Library — tsup (esbuild + dts)
+```ts
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/cli.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  minify: false,
+  external: ['react'],
+});
+```
+
+```jsonc
+// package.json — modern dual package
+{
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./cli": "./dist/cli.js"
+  },
+  "files": ["dist"]
+}
+```
+
+### App backend — esbuild
+```ts
+// build.ts
+import { build } from 'esbuild';
+
+await build({
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: 'dist/index.js',
+  sourcemap: true,
+  packages: 'external', // node_modules 는 번들 X
+  banner: { js: `import { createRequire } from 'module'; const require = createRequire(import.meta.url);` },
+});
+```
+
+### Dev — tsx (no build)
+```bash
+npx tsx watch src/index.ts
+```
+
+### App frontend — Vite
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    target: 'es2022',
+    sourcemap: true,
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          react: ['react', 'react-dom'],
+          query: ['@tanstack/react-query'],
+        },
+      },
+    },
+  },
+});
+```
+
+### swc (Nest, Next 의 일부)
+```jsonc
+// .swcrc
+{
+  "jsc": {
+    "parser": { "syntax": "typescript", "decorators": true },
+    "target": "es2022",
+    "transform": { "decoratorMetadata": true }
+  },
+  "module": { "type": "es6" }
+}
+```
+
+### DTS bundle (single .d.ts)
+```ts
+// rollup.config.ts
+import dts from 'rollup-plugin-dts';
+export default { input: 'dist/index.d.ts', output: { file: 'dist/index.d.ts', format: 'es' }, plugins: [dts()] };
+```
+
+### Bundle analyze
+```bash
+# Vite
+npx vite-bundle-visualizer
+
+# webpack-style
+npx esbuild-visualizer --metadata=meta.json
+```
+
+### Watch + restart (Node)
+```bash
+npx tsx watch --clear-screen=false src/index.ts
+# 또는 nodemon + esbuild
+```
+
+## 🤔 의사결정 기준
+| 산출물 | 도구 |
+|---|---|
+| npm 라이브러리 | tsup |
+| Node CLI / 서버 | tsx (dev) + esbuild (build) |
+| React 앱 | Vite (CSR) / Next (SSR) |
+| Monorepo + Bazel-like | Turborepo + tsup/Vite |
+| Type 만 검사 | `tsc --noEmit` |
+| ESM only | `module: nodenext` + `.js` extension |
+| Decorator + reflect-metadata | swc |
+
+## ❌ 안티패턴
+- **tsc 로 빌드 + 큰 코드**: 느림. swc/esbuild 가 10-100배 빠름.
+- **DTS 빌드 누락**: 타입 안 노출.
+- **Sourcemap 없음 prod**: 에러 stack 의미 없음.
+- **node_modules 같이 번들**: 거대 번들. backend 는 external.
+- **CJS only**: 새 ESM 라이브러리 못 import.
+- **ESM only**: legacy 사용자 못 require.
+- **`exports` field 없음**: dual package hazard, subpath import 안 됨.
+
+## 🤖 LLM 활용 힌트
+- Library = tsup, Server = esbuild, Client = Vite/Next.
+- DTS 생성 + sourcemap + dual package.
+- tsc 는 검사 전담, build 는 esbuild.
+
+## 🔗 관련 문서
+- [[TS_tsconfig_Strategy]]
+- [[TS_Monorepo_Patterns]]
+- [[JS_Module_System_ESM_CJS]]