{{tag>[cli typescript compiler javascript node.js]}}

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

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

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

<code bash>
npm install --save-dev typescript
npx tsc --version
</code>

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

<code bash>
yarn add --dev typescript
yarn tsc --version

pnpm add --save-dev typescript
pnpm exec tsc --version
</code>

<note>TypeScript upstream은 ''tsc'' 자체에 대한 별도 APT, DNF/YUM, Homebrew, ''winget'' 설치 절차를 제공하지 않는다. 각 OS에서 공식적으로 지원되는 Node.js 설치를 준비한 다음 프로젝트 패키지 매니저로 설치한다.</note>

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

<code bash>
npm install --global typescript
tsc --version
</code>

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

<code powershell>
Install-Package Microsoft.TypeScript.MSBuild
</code>

===== Usage =====
<code bash>
npx tsc
npx tsc src/index.ts
npx tsc --project tsconfig.production.json
npx tsc --noEmit
npx tsc --watch
npx tsc --build
</code>

  * ''<color #c3c3c3>**npx tsc**</color> <color #22b14c>[OPTIONS]</color> <color #7092be>[FILE...]</color>''
  * ''<color #c3c3c3>**npx tsc**</color> <color #22b14c>**--project**</color> <color #7092be>PATH</color>''
  * ''<color #c3c3c3>**npx tsc**</color> <color #22b14c>**--build**</color> <color #7092be>[PROJECT...]</color>''

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

==== Build and watch ====
  * ''<color #22b14c>**--watch**</color>'', ''<color #22b14c>**-w**</color>'': 입력 변경을 감시하고 다시 컴파일한다.
  * ''<color #22b14c>**--build**</color>'', ''<color #22b14c>**-b**</color>'': project reference와 의존성을 incremental build한다.
  * ''<color #22b14c>**--build --dry**</color>'': build 또는 clean 대상만 표시한다.
  * ''<color #22b14c>**--build --force**</color>'': 최신 상태여도 모든 프로젝트를 다시 build한다.
  * ''<color #22b14c>**--build --clean**</color>'': build mode의 생성물을 삭제한다.

<note warning>''--build --clean''은 project reference 설정에 기록된 출력물을 삭제한다. 먼저 ''--build --clean --dry''로 대상을 확인한다.</note>

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

===== Examples =====
==== Initialize and type-check a project ====
<code bash>
npm install --save-dev typescript
npx tsc --init
npx tsc --noEmit
</code>

==== Compile a specific project ====
<code bash>
npx tsc --project ./tsconfig.production.json
</code>

==== Compile files directly ====
<code bash>
npx tsc src/index.ts src/worker.ts --target es2022 --module nodenext --outDir dist
</code>

<note important>파일 이름을 직접 넘기면 가까운 ''tsconfig.json''을 사용하지 않는다. 프로젝트 설정이 필요하면 파일 목록 대신 ''--project''를 사용한다.</note>

==== Generate declarations only ====
<code bash>
npx tsc src/index.ts --declaration --emitDeclarationOnly --outDir types
</code>

==== Build project references ====
<code bash>
npx tsc --build --verbose
npx tsc --build --dry
</code>

===== Config =====
''tsconfig.json''의 위치, 주요 필드, 상속, project reference, 검증 방법은 [[tsc:config:ko|tsconfig.json 구성]]을 참고한다.

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

<code bash>
npx tsc --help
npx tsc --help --all
npx tsc --version
</code>

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

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

<code bash>
npx tsc --project ./tsconfig.json --showConfig
</code>

==== Unexpected files are compiled ====
최종 설정과 대상 파일을 차례로 확인한다.

<code bash>
npx tsc --showConfig
npx tsc --listFilesOnly
</code>

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

===== Compatibility =====
  * option과 기본값은 TypeScript 버전에 따라 달라질 수 있으므로 프로젝트에 설치된 버전의 ''--help --all''과 [[https://www.typescriptlang.org/tsconfig/|TSConfig Reference]]를 기준으로 한다.
  * ''module'', ''moduleResolution'', ''target''은 실제 runtime과 bundler가 이해하는 형식에 맞춰 함께 선택한다.
  * <del>''--out''</del>은 더 이상 지원되지 않는 legacy option이다. 필요한 경우 ''--outFile''을 검토하되 module format 제약을 확인한다.

===== See Also =====
  * [[tsc:config:ko|tsconfig.json 구성]]
  * [[tsx|tsx]]
  * [[node.js:ko|Node.js]]
  * [[node.js:npm|npm]]
  * [[https://www.typescriptlang.org/download/|TypeScript 설치 문서]]
  * [[https://www.typescriptlang.org/docs/handbook/compiler-options.html|tsc CLI Options]]

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

{{indexmenu>.#1|js}}