SWC
SWC(Speedy Web Compiler)는 Rust 기반의 확장 가능한 플랫폼입니다. Next.js와 Deno 내부에서 사용되는 컴파일러입니다.
사용 시점
- 고성능 JavaScript/TypeScript 트랜스파일: Babel을 Rust 기반 컴파일러로 교체하여 최대 20배 빠른 속도를 제공합니다.
- Next.js 및 최신 번들러 파이프라인: React JSX, TSX, 최신 ECMAScript 기능 및 Webpack/Turbopack 자산을 트랜스파일합니다.
- 프로그래매틱 AST 조작 및 코드 생성:
@swc/coreNode.js API를 사용하여 빠른 맞춤형 빌드 도구를 구축합니다. - 프로덕션 자산 축소(Minification):
@swc/core미니파이어를 사용하여 JS 및 CSS 번들을 극도로 빠른 속도로 축소합니다.
빠른 시작
1. 최소 .swcrc
{
"$schema": "https://json.schemastore.org/swcrc",
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": true,
"decorators": true
},
"transform": {
"react": {
"runtime": "automatic"
}
},
"target": "es2022"
},
"minify": false
}
2. CLI를 통한 컴파일
npx @swc/cli src -d dist
핵심 개념
프로덕션 SWC 설정 (.swcrc)
최신 TypeScript, React 19 JSX 런타임 및 모듈 트랜스파일 설정:
{
"$schema": "https://json.schemastore.org/swcrc",
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": true,
"decorators": true,
"dynamicImport": true
},
"transform": {
"react": {
"runtime": "automatic",
"refresh": true
}
},
"target": "es2022",
"loose": false,
"externalHelpers": true,
"keepClassNames": true,
"minify": {
"compress": {
"unused": true,
"drop_console": true
},
"mangle": true
}
},
"module": {
"type": "es6"
},
"minify": true,
"sourceMaps": true
}
@swc/core API를 사용한 프로그래매틱 컴파일
Node.js 스크립트에서 소스 파일을 비동기적으로 트랜스파일:
import swc from "@swc/core";
import fs from "node:fs/promises";
async function compileTypeScript(filePath) {
const code = await fs.readFile(filePath, "utf-8");
const output = await swc.transform(code, {
filename: filePath,
sourceMaps: true,
jsc: {
parser: { syntax: "typescript", tsx: true },
target: "es2022",
},
module: { type: "commonjs" },
});
console.log("Transpiled Code:\n", output.code);
if (output.map) {
console.log("Source Map Generated");
}
}
compileTypeScript("./src/index.ts");
고속 CLI 트랜스파일
SWC 명령줄을 사용하여 디렉터리 트리를 직접 컴파일:
# 소스 맵과 함께 src/에서 dist/로 트랜스파일
npx swc src -d dist --copy-files --source-maps
# swcpack을 사용하여 트랜스파일 및 번들링
npx swc src/index.ts -o dist/bundle.js --minify
일반적인 패턴
@swc/jest로 Jest 테스트 가속화
문제: ts-jest를 사용한 TypeScript 트랜스파일로 인해 테스트 스위트 실행 속도가 매우 느립니다.
해결책: ts-jest를 @swc/jest로 교체합니다.
// jest.config.js
module.exports = {
transform: {
"^.+\\.(t|j)sx?$": [
"@swc/jest",
{
jsc: {
transform: {
react: { runtime: "automatic" },
},
},
},
],
},
};
SWC 번들링 및 축소(Minification) 파이프라인
문제: 프로덕션 빌드 스크립트에 빠른 축소(Minification)가 필요합니다.
해결책: .swcrc 내에서 minify 옵션을 활성화합니다.
{
"minify": true,
"jsc": {
"minify": {
"compress": {
"drop_console": true
},
"mangle": true
}
}
}
모범 사례 (2026)
- 해야 할 것:
@swc/helpers를 설치하고externalHelpers: true를 활성화하여 트랜스파일러 런타임 헬퍼 스텁 복제를 방지합니다. - 해야 할 것: SWC는 타입 검사를 수행하지 않으므로 CI/CD 파이프라인에서 SWC와 함께
tsc --noEmit을 사용합니다. - 해야 할 것: 네이티브 최신 브라우저 기능을 활용하기 위해
target: "es2022"이상으로 설정합니다. - 해야 할 것:
@swc/jest또는@swc/register를 사용하여 단위 테스트 실행을 획기적으로 가속화합니다. - 하지 말아야 할 것: 꼭 필요하지 않은 한 Babel 플러그인에 의존하지 마십시오. 네이티브 SWC 플러그인(Wasm 플러그인)이 있는지 확인하십시오.
- 하지 말아야 할 것:
.swc빌드 캐시 디렉터리를 Git 저장소에 커밋하지 마십시오. - 하지 말아야 할 것: 프로덕션 문제 해결을 위해 소스 맵을 생성하지 않고 SWC 축소(Minification)를 실행하지 마십시오.
문제 해결
| 오류 / 증상 | 원인 | 해결책 |
|---|---|---|
failed to handle: error parsing typescript | .swcrc에서 플래그를 활성화하지 않고 TypeScript 구문(예: JSX 또는 데코레이터) 사용 | jsc.parser에 "syntax": "typescript", "tsx": true, "decorators": true가 있는지 확인합니다. |
데코레이터 메타데이터가 출력되지 않음 (Reflect.getMetadata가 undefined 반환) | transform.legacyDecorator 및 transform.decoratorMetadata가 설정되지 않음 | jsc.transform 내에 "legacyDecorator": true 및 "decoratorMetadata": true를 설정합니다. |
Cannot find module '@swc/core-darwin-arm64' | npm/yarn 설치 중 네이티브 바이너리 설치 실패 | npm install --force @swc/core를 실행하여 대상 아키텍처에 대한 네이티브 바이너리 가져오기를 트리거합니다. |