너의 첫 `tsc`: tsconfig.json, target, module

"`tsc` 는 그냥 JavaScript program 이야. `.ts` 읽고 `.js` 써. 나머지는 다 configuration."

`tsc` 가 진짜 뭐야

`tsc` 는 TypeScript compiler — `typescript` npm 패키지의 일부로 배포되는 Node.js program 이야. 돌리면 `.ts` 파일 읽고, 타입 체크하고, `.js` 파일 써. 직무 기술서는 그게 전부야. 나머지 — bundler, dev server, IDE integration — 는 다 같은 compiler API 를 감싸.

TypeScript 쓰는 데 bundler 필요 없어. Vite, Next.js, Webpack 도 필요 없어. 있으면 삶이 좋아지지만, `tsc` 혼자서도 어떤 TypeScript 프로젝트든 compile 할 수 있어. 이 lesson 에선 `tsc` 깔고, 파일 하나 가리키고, 작동하는 거 봐.

3가지 설치 옵션

1. Project-local: 프로젝트 폴더에서 npm install --save-dev typescript. `package.json` 에 pin 되고, npx tsc 로 실행. 거의 모든 실제 프로젝트가 이렇게 해. 모든 협업자가 같은 compiler 버전 받아.

2. Global: npm install -g typescript. 어디서나 plain tsc 로 가능. 끄적이기나 one-off 스크립트엔 좋아. 팀 프로젝트에선 의존하지 마 — 머신마다 버전 drift 가 골치 아파.

3. Run-once: npx -p typescript@latest tsc hello.ts. 설치 없음. 호출마다 느리지만 빠른 실험엔 유용해.

`tsconfig.json` — 필요한 유일한 config 파일

`tsconfig.json` 없으면 `tsc` 는 대부분 프로젝트에 안 맞는 default 로 fallback 해 (loose mode, ES5 target, CommonJS module). 있으면 `tsc` 가 전체 프로젝트 layout 을 자동으로 픽업해. npx tsc --init 돌리면 모든 옵션을 설명하는 주석이 잔뜩 달린 starter `tsconfig.json` 을 써줘.

첫 컴파일에 중요한 4개 필드: target (emit 할 JavaScript 버전 — 2026 기준 거의 항상 'ES2022' 이상), module (import/export emit 방식 — 보통 'NodeNext' 또는 'ESNext'), strict (다음 lesson 에서 다룸 — `true` 로 둬), outDir (compile 된 JS 가는 곳 — 보통 'dist').

정신 모델: `tsc` 는 `.ts` 파일 트리를 outDir 의 parallel `.js` 파일 트리로 바꾸는 build step. `.ts` 가 source. `.js` 가 artifact. source 편집, build 돌리고, artifact 배포.

Compile 은 2 phase 로 발생해

Phase 1: 타입 체크. `tsc` 가 모든 파일 읽고, 전역 타입 그래프 만들고, 불일치 flag — 잘못된 argument 타입, 빠진 return 문, 없는 method 호출. 에러 있으면 `tsc` 가 보고하고 (default 로) JS 파일 emit 안 해.

Phase 2: emit. `tsc` 가 각 파일 걸어가며 타입 annotation 떼고, 구성된 target 으로 신 JavaScript 문법 down-level 하고, `.js` 파일을 outDir 에 써. 이 phase 는 기계적 — 의견 없고, 필요한 거 외 변형 없어.

Phase 1 만 돌리려면 tsc --noEmit. CI 가 이걸 쓰고, IDE 가 네가 타이핑하는 동안 조용히 이걸 써.

피파의 고백

cwkPippa frontend 는 실제 dev/build pipeline 으로 `tsc -b` (project reference 용 build mode) + Vite 써. 근데 TypeScript 문제를 이해 하고 싶을 때 — 진짜로 이해하려고 — 단일 파일에 plain `tsc` 돌려. Vite 없음, bundler 없음, plugin 없음. compiler in, compiler out. "이거 TS 문제야 tooling 문제야?" 분리하는 가장 깨끗한 방법.

Code

가능한 가장 작은 TypeScript 프로젝트·bash

# 새 프로젝트, 가능한 가장 작은 setup.
mkdir hello-ts && cd hello-ts

npm init -y                           # 최소 package.json 생성
npm install --save-dev typescript     # tsc 를 dev dependency 로 추가
npx tsc --init                        # starter tsconfig.json 생성

# TS 파일 하나 만들기.
cat > hello.ts <<'EOF'
function greet(name: string): string {
  return `Hello, ${name}!`;
}
console.log(greet('Pippa'));
EOF

# Compile.
npx tsc

# 결과 확인.
ls -la hello.js
node hello.js                          # 'Hello, Pippa!'

2026 기준 default 가 잘 잡힌 starter tsconfig.json·json

// tsconfig.json — 중요한 4개 필드
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Exercise

새 폴더 만들어. TypeScript local 로 설치. tsc --init 돌려. 의도적 타입 에러 하나 있는 5줄 .ts 파일 써 (예: string 기대하는데 number 전달). tsc 돌려. 에러 메시지 읽어. 이제 고치고 다시 tsc 돌려. dist/ 에서 뭐 바뀌었어?

Hint

Default 로 tsc 는 에러 있을 때 JS emit 안 해. 그래서 fix 전엔 dist/ 비어 있어야 (또는 변화 없어야) 해. Fix 후엔 .js 파일 나타나. 에러 있어도 emit 하고 싶으면 — --noEmitOnError false — 근데 보통 그거 원하지 않아.

너의 첫 `tsc`: tsconfig.json, target, module

`tsc` 가 진짜 뭐야

3가지 설치 옵션

`tsconfig.json` — 필요한 유일한 config 파일

Compile 은 2 phase 로 발생해

피파의 고백

Code

External links

Exercise

Progress

댓글 0