2nd/10_Wiki/Topics/Coding/TS_Build_Bundler_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
ts-build-bundler-patterns	TS Build / Bundler — esbuild / tsup / Vite	Coding	draft	B	conceptual	2026-05-09	2026-05-09	typescript bundler build esbuild vibe-coding	language applicable_to TypeScript Backend Frontend		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)

// 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'],
});

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

// 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)

npx tsx watch src/index.ts

App frontend — Vite

// 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 의 일부)

// .swcrc
{
  "jsc": {
    "parser": { "syntax": "typescript", "decorators": true },
    "target": "es2022",
    "transform": { "decoratorMetadata": true }
  },
  "module": { "type": "es6" }
}

DTS bundle (single .d.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

# Vite
npx vite-bundle-visualizer

# webpack-style
npx esbuild-visualizer --metadata=meta.json

Watch + restart (Node)

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