esbuild 완벽 가이드 | 초고속 번들러·TypeScript·Plugins·실전 활용

이 글의 핵심

esbuild로 초고속 번들링을 구현하는 완벽 가이드입니다. Go 기반 성능, TypeScript, JSX, Plugins, Watch Mode까지 실전 예제로 정리했습니다.

실무 경험 공유: Webpack에서 esbuild로 전환하면서, 빌드 시간이 10분에서 10초로 단축된 경험을 공유합니다.

들어가며: “빌드가 너무 느려요”

실무에서 마주치는 문제들

TypeScript 빌드가 느려요

tsc는 느립니다. esbuild는 100배 빠릅니다. 번들링이 느려요

Webpack은 느립니다. esbuild는 10~100배 빠릅니다. 빠른 피드백이 필요해요

느린 빌드는 생산성을 떨어뜨립니다. esbuild는 즉시 피드백을 제공합니다.

1. esbuild란?

핵심 특징

esbuild는 Go로 작성된 초고속 JavaScript 번들러입니다. 주요 장점

• 초고속: 10~100배 빠름
• TypeScript: 네이티브 지원
• JSX: 네이티브 지원
• Tree Shaking: 자동
• Source Maps: 지원

---

2. 설치 및 기본 사용

설치

npm install -D esbuild

CLI

# 번들링
esbuild src/index.ts --bundle --outfile=dist/bundle.js
# Minify
esbuild src/index.ts --bundle --minify --outfile=dist/bundle.js
# Watch
esbuild src/index.ts --bundle --watch --outfile=dist/bundle.js

---

3. Build API

// build.js
const esbuild = require('esbuild');
esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ['es2020'],
  outfile: 'dist/bundle.js',
}).catch(() => process.exit(1));

package.json

{
  "scripts": {
    "build": "node build.js"
  }
}

---

4. TypeScript

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  loader: {
    '.ts': 'ts',
    '.tsx': 'tsx',
  },
});

---

5. React/JSX

esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  loader: {
    '.tsx': 'tsx',
  },
  jsxFactory: 'React.createElement',
  jsxFragment: 'React.Fragment',
});

---

6. Watch Mode

const ctx = await esbuild.context({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
});
await ctx.watch();
console.log('Watching...');

---

7. Dev Server

const ctx = await esbuild.context({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
});
await ctx.serve({
  servedir: 'public',
  port: 3000,
});
console.log('Server running on http://localhost:3000');

---

8. Plugins

const envPlugin = {
  name: 'env',
  setup(build) {
    build.onResolve({ filter: /^env$/ }, (args) => ({
      path: args.path,
      namespace: 'env-ns',
    }));
    build.onLoad({ filter: /.*/, namespace: 'env-ns' }, () => ({
      contents: JSON.stringify(process.env),
      loader: 'json',
    }));
  },
};
esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  plugins: [envPlugin],
  outfile: 'dist/bundle.js',
});

---

9. 실전 예제: React 프로젝트

// build.js
const esbuild = require('esbuild');
const { copy } = require('esbuild-plugin-copy');
const isProduction = process.env.NODE_ENV === 'production';
esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  minify: isProduction,
  sourcemap: !isProduction,
  target: ['es2020'],
  outfile: 'dist/bundle.js',
  loader: {
    '.tsx': 'tsx',
    '.ts': 'ts',
  },
  define: {
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  },
  plugins: [
    copy({
      resolveFrom: 'cwd',
      assets: {
        from: ['./public/**/*'],
        to: ['./dist'],
      },
    }),
  ],
}).catch(() => process.exit(1));

---

10. 내부 구조와 한계: Go 병렬성·번들 그래프

esbuild는 Go로 작성되어 병렬 파싱·번들링에 강점이 있습니다. 입력 파일을 그래프로 펼친 뒤, 의존성이 없는 부분부터 동시에 처리하는 이미지로 이해하면 디버깅이 쉬워집니다. 반대로 말하면, 순환 참조나 동적 import() 해석 불가 같은 케이스는 “esbuild가 의도적으로 단순화한 부분”에서 막히기 쉽습니다.

타입 검사는 하지 않습니다. TypeScript는 트랜스파일(구문 제거) 수준이므로 CI에 tsc --noEmit 또는 typescript-eslint를 별도 게이트로 두는 것이 일반적인 프로덕션 패턴입니다. 또한 Decorator·일부 최신 제안 문법은 플래그·플러그인 없이는 커버되지 않을 수 있어, Babel/SWC와의 역할 분담을 문서화해 두면 팀 온보딩 비용이 줄어듭니다.

프로덕션 체크리스트(번들러 관점)

• define/inject: process.env 치환 누락으로 런타임 undefined가 나지 않았는지 확인합니다.
• external: Node 번들에서 pg, aws-sdk 같은 네이티브/대형 모듈을 외부화했는지 확인합니다.
• 소스맵: 프로덕션은 보통 끄거나 hidden-source-map에 해당하는 전략을 취하며, Sentry 등에만 업로드합니다.

---

11. 트러블슈팅

증상	흔한 원인	대응
Could not resolve "x"	browser 필드·조건부 export	alias·mainFields 조정
번들에 dev 의존성 포함	NODE_ENV 미설정	define + --packages=external 검토
두 개의 React	중복 해상	dedupe 또는 패키지 구조 정리
플러그인이 무시됨	onResolve 필터 불일치	디버그 로그로 경로 확인

---

정리 및 체크리스트

핵심 요약

• esbuild: 초고속 번들러
• Go 기반: 10~100배 빠름
• TypeScript: 네이티브 지원
• JSX: 네이티브 지원
• Tree Shaking: 자동
• Plugins: 확장 가능

구현 체크리스트

• esbuild 설치
• Build API 사용
• TypeScript 설정
• React/JSX 설정
• Watch Mode
• Dev Server
• Plugins 추가
• 프로덕션 빌드

---

같이 보면 좋은 글

• Vite 완벽 가이드
• Webpack 완벽 가이드
• Bun 완벽 가이드

---

이 글에서 다루는 키워드

esbuild, Bundler, Build Tools, TypeScript, Go, Performance, Frontend

자주 묻는 질문 (FAQ)

Q. Webpack을 완전히 대체할 수 있나요?

A. 간단한 프로젝트는 가능하지만, 복잡한 설정이 필요하면 Webpack이 더 적합합니다.

Q. Vite와 비교하면 어떤가요?

A. Vite는 esbuild를 내부적으로 사용합니다. Vite가 더 편리하고 esbuild가 더 빠릅니다.

Q. 타입 체크를 하나요?

A. 아니요, 타입을 제거만 합니다. tsc로 별도로 타입 체크를 해야 합니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, Vite, Remix 등이 esbuild를 사용하고 있습니다.