tsc

tsc는 TypeScript 소스의 타입을 검사하고 설정에 따라 JavaScript와 선언 파일을 생성하는 TypeScript compiler CLI이다.

• 인수 없이 실행하면 현재 디렉터리부터 상위로 탐색해 가장 가까운 tsconfig.json 프로젝트를 컴파일한다.
• 입력 파일을 명령줄에 직접 지정하면 tsconfig.json 설정을 무시하고 해당 파일을 compiler 기본값과 명령줄 옵션으로 처리한다.
• 프로젝트에서는 TypeScript 버전을 lockfile로 고정할 수 있도록 전역 설치보다 로컬 개발 의존성과 npx tsc 사용을 우선한다.

Debian / Ubuntu, RHEL / Fedora, macOS, Windows에서 Node.js와 npm을 준비한 뒤 프로젝트에 설치한다.

npm install --save-dev typescript
npx tsc --version

Yarn 또는 pnpm 프로젝트에서는 같은 패키지를 개발 의존성으로 추가한다.

yarn add --dev typescript
yarn tsc --version
 
pnpm add --save-dev typescript
pnpm exec tsc --version

기존 전역 설치 명령은 일회성 실험이나 시스템 전체에서 직접 tsc를 호출할 때 사용할 수 있다. 장기 유지 프로젝트에는 로컬 설치를 우선한다.

npm install --global typescript
tsc --version

Visual Studio의 MSBuild 기반 프로젝트는 NuGet Package Manager Console에서 compiler 패키지를 설치할 수 있다. Node.js client 설치와는 별도 경로이다.

Install-Package Microsoft.TypeScript.MSBuild

npx tsc
npx tsc src/index.ts
npx tsc --project tsconfig.production.json
npx tsc --noEmit
npx tsc --watch
npx tsc --build

• npx tsc [OPTIONS] [FILE…]
• npx tsc –project PATH
• npx tsc –build [PROJECT…]

• –help, -h: 일반 도움말을 표시한다.
• –help –all: 모든 compiler option을 표시한다.
• –version, -v: compiler 버전을 표시한다.
• –init: 현재 디렉터리에 tsconfig.json을 생성한다.
• –project PATH, -p PATH: 지정한 설정 파일 또는 tsconfig.json이 있는 디렉터리를 사용한다.
• –showConfig: 실제 적용할 최종 설정을 출력하고 컴파일하지 않는다.
• –listFilesOnly: compilation 대상 파일 이름만 출력한다.

• –watch, -w: 입력 변경을 감시하고 다시 컴파일한다.
• –build, -b: project reference와 의존성을 incremental build한다.
• –build –dry: build 또는 clean 대상만 표시한다.
• –build –force: 최신 상태여도 모든 프로젝트를 다시 build한다.
• –build –clean: build mode의 생성물을 삭제한다.

• –noEmit: 출력 파일을 만들지 않고 타입 검사만 한다.
• –declaration: .d.ts 선언 파일을 생성한다.
• –emitDeclarationOnly: JavaScript 없이 선언 파일만 생성한다.
• –outDir DIR: 생성 파일의 출력 디렉터리를 지정한다.
• –target VERSION: 생성할 JavaScript language version을 지정한다.
• –module KIND: 생성 코드의 module format과 관련 해석 동작을 지정한다.
• –moduleResolution MODE: module specifier를 파일로 해석하는 방식을 지정한다.
• –strict: strict type-checking option 묶음을 활성화한다.
• –pretty: 진단 메시지의 색상과 형식을 제어한다.
• –sourceMap: source map을 생성한다.
• –incremental: incremental compilation 정보를 저장한다.

npm install --save-dev typescript
npx tsc --init
npx tsc --noEmit

npx tsc --project ./tsconfig.production.json

npx tsc src/index.ts src/worker.ts --target es2022 --module nodenext --outDir dist

npx tsc src/index.ts --declaration --emitDeclarationOnly --outDir types

npx tsc --build --verbose
npx tsc --build --dry

tsconfig.json의 위치, 주요 필드, 상속, project reference, 검증 방법은 tsconfig.json 구성을 참고한다.

검증 환경에 tsc가 설치되어 있지 않아 특정 버전의 도움말 원문은 수록하지 않았다. 프로젝트에 설치된 버전을 기준으로 확인한다.

npx tsc --help
npx tsc --help --all
npx tsc --version

프로젝트 로컬 설치는 실행 파일을 전역 PATH에 추가하지 않는다. 프로젝트 루트에서 npx tsc, pnpm exec tsc, 또는 yarn tsc를 사용한다.

명령줄에 .ts 파일을 직접 지정했는지 확인한다. 설정 파일을 반드시 적용하려면 다음처럼 실행한다.

npx tsc --project ./tsconfig.json --showConfig

최종 설정과 대상 파일을 차례로 확인한다.

npx tsc --showConfig
npx tsc --listFilesOnly

전역 tsc 대신 프로젝트의 typescript 개발 의존성을 lockfile에 기록하고 package manager를 통해 실행한다.

• option과 기본값은 TypeScript 버전에 따라 달라질 수 있으므로 프로젝트에 설치된 버전의 –help –all과 TSConfig Reference를 기준으로 한다.
• module, moduleResolution, target은 실제 runtime과 bundler가 이해하는 형식에 맞춰 함께 선택한다.
• –out은 더 이상 지원되지 않는 legacy option이다. 필요한 경우 –outFile을 검토하되 module format 제약을 확인한다.

• tsconfig.json 구성
• tsx
• Node.js
• npm
• TypeScript 설치 문서
• tsc CLI Options

• codex:: 2026-08-04 프로젝트 로컬 설치, 주요 명령과 옵션, 안전한 예제, 문제 해결, 호환성 정보를 추가하고 언어 head page로 이전함.