---
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]]