tsc CLI 옵션

tsc CLI 옵션 (Compiler Options)

tsc는 명령줄에서 바로 쓸 수 있는 도구예요. tsconfig.json을 기반으로 프로젝트를 컴파일할 수도 있고, 특정 파일만 지정해 컴파일할 수도 있어요. 이 문서에서는 명령줄에서 쓸 수 있는 모든 옵션을 빠짐없이 살펴볼게요.

출처: TypeScript 핸드북 - tsc CLI Options

CLI 사용하기 (Using the CLI)

tsc를 로컬에서 실행하면 가장 가까운 tsconfig.json이 정의하는 프로젝트를 컴파일하고, 원하는 파일들의 glob을 인자로 넘겨 TypeScript 파일 집합을 컴파일할 수도 있어요. 명령줄에서 입력 파일을 지정하면 tsconfig.json 파일은 무시됩니다.

# Run a compile based on a backwards look through the fs for a tsconfig.json
tsc

# Emit JS for just the index.ts with the compiler defaults
tsc index.ts

# Emit JS for any .ts files in the folder src, with the default settings
tsc src/*.ts

# Emit files referenced in with the compiler settings from tsconfig.production.json
tsc --project tsconfig.production.json

# Emit d.ts files for a js file with showing compiler options which are booleans
tsc index.js --declaration --emitDeclarationOnly

# Emit a single .js file from two files via compiler options which take string arguments
tsc app.ts util.ts --target esnext --outfile index.js

컴파일러 옵션 (Compiler Options)

tsconfig에서 컴파일러 옵션에 대한 더 자세한 정보를 찾고 있다면 TSConfig Reference를 확인하세요.

CLI 명령어 (CLI Commands)

Flag	Type
`--all`	`boolean`
모든 컴파일러 옵션을 보여줍니다.
`--help`	`boolean`
CLI에 대한 도움말 정보를 로컬에서 제공합니다.
`--ignoreConfig`	`boolean`
발견된 tsconfig를 무시하고, 명령줄 옵션과 파일로 빌드합니다.
`--init`	`boolean`
TypeScript 프로젝트를 초기화하고 tsconfig.json 파일을 만듭니다.
`--listFilesOnly`	`boolean`
컴파일에 포함된 파일들의 이름을 출력한 뒤 처리를 멈춥니다.
`--locale`	`string`
TypeScript가 내는 메시지의 언어를 설정합니다. 이는 출력(emit)에는 영향을 주지 않습니다.
`--project`	`string`
설정 파일의 경로, 또는 'tsconfig.json'이 있는 폴더의 경로가 주어진 프로젝트를 컴파일합니다.
`--showConfig`	`boolean`
빌드하는 대신 최종 설정을 출력합니다.
`--version`	`boolean`
컴파일러의 버전을 출력합니다.

빌드 옵션 (Build Options)

Flag	Type
`--build`	`boolean`
하나 이상의 프로젝트와 그 의존성을, 오래된 경우 빌드합니다.
`--clean`	`boolean`
모든 프로젝트의 출력물을 삭제합니다.
`--dry`	`boolean`
무엇이 빌드될지 보여줍니다('--clean'과 함께 지정하면 무엇이 삭제될지도요).
`--force`	`boolean`
최신 상태로 보이는 프로젝트를 포함해 모든 프로젝트를 빌드합니다.
`--verbose`	`boolean`
자세한 로깅을 활성화합니다.

Watch 옵션 (Watch Options)

Flag	Type
`--excludeDirectories`	`list`
감시(watch) 과정에서 디렉터리 목록을 제거합니다.
`--excludeFiles`	`list`
watch 모드의 처리에서 파일 목록을 제거합니다.
`--fallbackPolling`	`fixedinterval`, `priorityinterval`, `dynamicpriority`, or `fixedchunksize`
시스템의 네이티브 파일 watcher가 소진되면 watcher가 어떤 방식을 사용할지 지정합니다.
`--synchronousWatchDirectory`	`boolean`
재귀적 감시를 기본 지원하지 않는 플랫폼에서 콜백을 동기적으로 호출하고 디렉터리 watcher의 상태를 갱신합니다.
`--watch`	`boolean`
입력 파일을 감시합니다.
`--watchDirectory`	`usefsevents`, `fixedpollinginterval`, `dynamicprioritypolling`, or `fixedchunksizepolling`
재귀적 파일 감시 기능이 없는 시스템에서 디렉터리를 어떻게 감시할지 지정합니다.
`--watchFile`	`fixedpollinginterval`, `prioritypollinginterval`, `dynamicprioritypolling`, `fixedchunksizepolling`, `usefsevents`, or `usefseventsonparentdirectory`
TypeScript의 watch 모드가 어떻게 동작할지 지정합니다.

컴파일러 플래그 (Compiler Flags)

Flag	Type	Default
`--allowArbitraryExtensions`	`boolean`	`false`
선언 파일(declaration file)이 존재한다면 어떤 확장자의 파일도 가져오는 것을 활성화합니다.
`--allowImportingTsExtensions`	`boolean`	`true` if `rewriteRelativeImportExtensions`; `false` otherwise.
import가 TypeScript 파일 확장자를 포함하도록 허용합니다.
`--allowJs`	`boolean`	`false`, unless `checkJs` is set
JavaScript 파일이 프로그램의 일부가 되도록 허용합니다. 이 파일들에서 에러를 얻으려면 `checkJS` 옵션을 사용하세요.
`--allowSyntheticDefaultImports`	`boolean`	`true` if `esModuleInterop` is enabled, `module` is `system`, or `moduleResolution` is `bundler`; `false` otherwise.
모듈에 기본 export가 없을 때 'import x from y'를 허용합니다.
`--allowUmdGlobalAccess`	`boolean`	`false`
모듈에서 UMD 전역(globals)에 접근하는 것을 허용합니다.
`--allowUnreachableCode`	`boolean`
도달 불가능한 코드에 대한 에러 보고를 비활성화합니다.
`--allowUnusedLabels`	`boolean`
사용되지 않는 레이블에 대한 에러 보고를 비활성화합니다.
`--alwaysStrict`	`boolean`	`true` if `strict`; `false` otherwise.
'use strict'가 항상 출력되도록 합니다.
`--assumeChangesOnlyAffectDirectDependencies`	`boolean`	`false`
`incremental`과 `watch` 모드를 사용하는 프로젝트에서, 파일 내 변경이 그 파일에 직접 의존하는 파일에만 영향을 준다고 가정하게 합니다.
`--baseUrl`	`string`
베어 스펙시파이어(bare specifier) 모듈 이름을 해석할 기준 디렉터리를 지정합니다.
`--charset`	`string`	`utf8`
더 이상 지원되지 않습니다. 초기 버전에서는 파일을 읽을 텍스트 인코딩을 수동으로 설정했습니다.
`--checkJs`	`boolean`	`false`
타입 검사되는 JavaScript 파일에서 에러 보고를 활성화합니다.
`--composite`	`boolean`	`false`
TypeScript 프로젝트가 프로젝트 참조(project references)와 함께 쓰일 수 있게 하는 제약을 활성화합니다.
`--customConditions`	`list`
import를 해석할 때 resolver 고유의 기본값에 추가로 설정할 조건들입니다.
`--declaration`	`boolean`	`true` if `composite`; `false` otherwise.
프로젝트의 TypeScript 및 JavaScript 파일로부터 .d.ts 파일을 생성합니다.
`--declarationDir`	`string`
생성된 선언 파일의 출력 디렉터리를 지정합니다.
`--declarationMap`	`boolean`	`false`
d.ts 파일용 소스맵(sourcemaps)을 생성합니다.
`--diagnostics`	`boolean`	`false`
빌드 후 컴파일러 성능 정보를 출력합니다.
`--disableReferencedProjectLoad`	`boolean`	`false`
TypeScript가 자동으로 로드하는 프로젝트의 수를 줄입니다.
`--disableSizeLimit`	`boolean`	`false`
TypeScript 언어 서버에서 JavaScript 파일의 전체 소스 코드 크기에 대한 20mb 제한을 제거합니다.
`--disableSolutionSearching`	`boolean`	`false`
편집 시 다중 프로젝트 참조 검사에서 프로젝트를 제외합니다.
`--disableSourceOfProjectReferenceRedirect`	`boolean`	`false`
복합(composite) 프로젝트를 참조할 때 선언 파일 대신 소스 파일을 선호하는 것을 비활성화합니다.
`--downlevelIteration`	`boolean`	`false`
반복(iteration)에 대해 더 규격을 준수하지만 장황하고 성능이 낮은 JavaScript를 출력합니다.
`--emitBOM`	`boolean`	`false`
출력 파일의 시작 부분에 UTF-8 바이트 오더 마크(BOM)를 출력합니다.
`--emitDeclarationOnly`	`boolean`	`false`
JavaScript 파일이 아닌 d.ts 파일만 출력합니다.
`--emitDecoratorMetadata`	`boolean`	`false`
소스 파일의 데코레이트된 선언에 대한 design-type 메타데이터를 출력합니다.
`--erasableSyntaxOnly`	`boolean`	`false`
ECMAScript의 일부가 아닌 런타임 구조를 허용하지 않습니다.
`--esModuleInterop`	`boolean`	`true` if `module` is `node16`, `nodenext`, or `preserve`; `false` otherwise.
CommonJS 모듈 가져오기 지원을 쉽게 하기 위해 추가 JavaScript를 출력합니다. 이는 타입 호환을 위해 `allowSyntheticDefaultImports`를 활성화합니다.
`--exactOptionalPropertyTypes`	`boolean`	`false`
선택적 프로퍼티 타입을 `undefined`를 추가하지 않고 작성된 그대로 해석합니다.
`--experimentalDecorators`	`boolean`	`false`
TC39 stage 2 초안 데코레이터에 대한 실험적 지원을 활성화합니다.
`--explainFiles`	`boolean`	`false`
컴파일 중 읽은 파일과, 그 파일이 포함된 이유를 출력합니다.
`--extendedDiagnostics`	`boolean`	`false`
빌드 후 더 자세한 컴파일러 성능 정보를 출력합니다.
`--forceConsistentCasingInFileNames`	`boolean`	`true`
import의 대소문자가 올바른지 보장합니다.
`--generateCpuProfile`	`string`	`profile.cpuprofile`
디버깅을 위해 컴파일러 실행의 v8 CPU 프로파일을 출력합니다.
`--generateTrace`	`string`
이벤트 추적과 타입 목록을 생성합니다.
`--importHelpers`	`boolean`	`false`
파일별로 포함하는 대신, 프로젝트당 한 번 tslib에서 헬퍼 함수를 가져오는 것을 허용합니다.
`--importsNotUsedAsValues`	`remove`, `preserve`, or `error`	`remove`
타입에만 사용되는 import에 대한 출력/검사 동작을 지정합니다.
`--incremental`	`boolean`	`true` if `composite`; `false` otherwise.
프로젝트의 증분 컴파일을 가능하게 하기 위해 .tsbuildinfo 파일을 저장합니다.
`--inlineSourceMap`	`boolean`	`false`
출력된 JavaScript 안에 소스맵 파일을 포함합니다.
`--inlineSources`	`boolean`	`false`
출력된 JavaScript 안의 소스맵에 소스 코드를 포함합니다.
`--isolatedDeclarations`	`boolean`	`false`
다른 도구가 선언 파일을 쉽게 생성할 수 있도록 export에 충분한 표기를 요구합니다.
`--isolatedModules`	`boolean`	`true` if `verbatimModuleSyntax`; `false` otherwise.
각 파일이 다른 import에 의존하지 않고 안전하게 트랜스파일될 수 있도록 보장합니다.
`--jsx`	`preserve`, `react`, `react-native`, `react-jsx`, or `react-jsxdev`
어떤 JSX 코드가 생성되는지 지정합니다.
`--jsxFactory`	`string`	`React.createElement`
React JSX 출력을 대상으로 할 때 사용할 JSX 팩토리 함수를 지정합니다. 예: 'React.createElement' 또는 'h'.
`--jsxFragmentFactory`	`string`	`React.Fragment`
React JSX 출력을 대상으로 할 때 프래그먼트에 사용할 JSX Fragment 참조를 지정합니다. 예: 'React.Fragment' 또는 'Fragment'.
`--jsxImportSource`	`string`	`react`
`jsx: react-jsx*`를 사용할 때 JSX 팩토리 함수를 가져오는 데 쓰는 모듈 스펙시파이어를 지정합니다.
`--keyofStringsOnly`	`boolean`	`false`
keyof가 문자열, 숫자, 심볼이 아닌 오직 문자열만 반환하게 합니다. 레거시 옵션입니다.
`--lib`	`list`
대상 런타임 환경을 설명하는 번들 라이브러리 선언 파일 집합을 지정합니다.
`--libReplacement`	`boolean`	`false`
기본 `lib` 파일을 사용자 정의 파일로 대체하는 것을 활성화합니다.
`--listEmittedFiles`	`boolean`	`false`
컴파일 후 출력된 파일들의 이름을 출력합니다.
`--listFiles`	`boolean`	`false`
컴파일 중 읽은 모든 파일을 출력합니다.
`--mapRoot`	`string`
디버거가 생성된 위치 대신 맵 파일을 찾을 위치를 지정합니다.
`--maxNodeModuleJsDepth`	`number`	`0`
`node_modules`에서 JavaScript 파일을 검사하는 데 쓰는 최대 폴더 깊이를 지정합니다. `allowJs`가 있을 때만 적용됩니다.
`--module`	`none`, `commonjs`, `amd`, `umd`, `system`, `es6`/`es2015`, `es2020`, `es2022`, `esnext`, `node16`, `node18`, `node20`, `nodenext`, or `preserve`	`CommonJS` if `target` is `ES5`; `ES6`/`ES2015` otherwise.
어떤 모듈 코드가 생성되는지 지정합니다.
`--moduleDetection`	`legacy`, `auto`, or `force`	"auto": Treat files with imports, exports, import.meta, jsx (with jsx: react-jsx), or esm format (with module: node16+) as modules.
파일이 스크립트인지 모듈인지 감지하는 데 쓰는 방법을 지정합니다.
`--moduleResolution`	`classic`, `node10`/`node`, `node16`, `nodenext`, or `bundler`	`Node10` if `module` is `CommonJS`; `Node16` if `module` is `Node16`, `Node18`, or `Node20`; `NodeNext` if `module` is `NodeNext`; `Bundler` if `module` is `Preserve`; `Classic` otherwise.
TypeScript가 주어진 모듈 스펙시파이어에서 파일을 어떻게 찾는지 지정합니다.
`--moduleSuffixes`	`list`
모듈을 해석할 때 검색할 파일 이름 접미사 목록입니다.
`--newLine`	`crlf` or `lf`	`lf`
파일 출력을 위한 줄바꿈 문자를 설정합니다.
`--noCheck`	`boolean`	`false`
전체 타입 검사를 비활성화합니다(오직 중요한 파싱과 출력 에러만 보고됩니다).
`--noEmit`	`boolean`	`false`
컴파일에서 파일 출력을 비활성화합니다.
`--noEmitHelpers`	`boolean`	`false`
컴파일 출력에서 `__extends` 같은 사용자 정의 헬퍼 함수의 생성을 비활성화합니다.
`--noEmitOnError`	`boolean`	`false`
타입 검사 에러가 보고되면 파일 출력을 비활성화합니다.
`--noErrorTruncation`	`boolean`	`false`
에러 메시지에서 타입을 잘라내는 것을 비활성화합니다.
`--noFallthroughCasesInSwitch`	`boolean`	`false`
switch문에서 빠져나가는(fallthrough) 경우에 대한 에러 보고를 활성화합니다.
`--noImplicitAny`	`boolean`	`true` if `strict`; `false` otherwise.
암시된 `any` 타입을 가진 표현식과 선언에 대한 에러 보고를 활성화합니다.
`--noImplicitOverride`	`boolean`	`false`
파생 클래스에서 오버라이딩하는 멤버가 override 수식어로 표시되도록 보장합니다.
`--noImplicitReturns`	`boolean`	`false`
함수에서 명시적으로 반환하지 않는 코드 경로에 대한 에러 보고를 활성화합니다.
`--noImplicitThis`	`boolean`	`true` if `strict`; `false` otherwise.
`this`에 `any` 타입이 주어질 때 에러 보고를 활성화합니다.
`--noImplicitUseStrict`	`boolean`	`false`
출력된 JavaScript 파일에 'use strict' 지시문을 추가하는 것을 비활성화합니다.
`--noLib`	`boolean`	`false`
기본 lib.d.ts를 포함한 라이브러리 파일을 전부 포함하는 것을 비활성화합니다.
`--noPropertyAccessFromIndexSignature`	`boolean`	`false`
인덱스 타입으로 선언된 키에 대해 인덱스 접근자 사용을 강제합니다.
`--noResolve`	`boolean`	`false`
`import`, `require` 또는 `<reference>`가 TypeScript가 프로젝트에 추가해야 하는 파일의 수를 늘리는 것을 허용하지 않습니다.
`--noStrictGenericChecks`	`boolean`	`false`
함수 타입에서 제네릭 시그니처의 엄격한 검사를 비활성화합니다.
`--noUncheckedIndexedAccess`	`boolean`	`false`
인덱스로 접근할 때 타입에 `undefined`를 추가합니다.
`--noUncheckedSideEffectImports`	`boolean`	`true`
부수 효과(side effect) import를 검사합니다.
`--noUnusedLocals`	`boolean`	`false`
지역 변수가 읽히지 않을 때 에러 보고를 활성화합니다.
`--noUnusedParameters`	`boolean`	`false`
함수 파라미터가 읽히지 않을 때 에러를 냅니다.
`--out`	`string`
더 이상 사용되지 않는 설정입니다. 대신 `outFile`을 사용하세요.
`--outDir`	`string`
모든 출력 파일을 위한 출력 폴더를 지정합니다.
`--outFile`	`string`
모든 출력을 하나의 JavaScript 파일로 묶는 파일을 지정합니다. `declaration`이 true면 모든 .d.ts 출력을 묶는 파일도 지정합니다.
`--paths`	`object`
import를 추가 조회 위치로 다시 매핑하는 항목 집합을 지정합니다.
`--plugins`	`list`
포함할 언어 서비스 플러그인 목록을 지정합니다.
`--preserveConstEnums`	`boolean`	`true` if `isolatedModules`; `false` otherwise.
생성된 코드에서 `const enum` 선언을 지우는 것을 비활성화합니다.
`--preserveSymlinks`	`boolean`	`false`
심볼릭 링크를 실제 경로(realpath)로 해석하는 것을 비활성화합니다. node의 같은 이름 플래그와 대응됩니다.
`--preserveValueImports`	`boolean`	`false`
그렇지 않으면 제거될, 사용되지 않는 가져온 값을 JavaScript 출력에 보존합니다.
`--preserveWatchOutput`	`boolean`	`false`
watch 모드에서 콘솔을 지우는 것을 비활성화합니다.
`--pretty`	`boolean`	`true`
컴파일러 에러를 읽기 쉽게 하기 위해 TypeScript 출력에서 색상과 서식을 활성화합니다.
`--reactNamespace`	`string`	`React`
`createElement`에 대해 호출되는 객체를 지정합니다. 이는 `react` JSX 출력을 대상으로 할 때만 적용됩니다.
`--removeComments`	`boolean`	`false`
주석 출력을 비활성화합니다.
`--resolveJsonModule`	`boolean`	`false`
.json 파일 가져오기를 활성화합니다.
`--resolvePackageJsonExports`	`boolean`	`true` when `moduleResolution` is `node16`, `nodenext`, or `bundler`; otherwise `false`
패키지 import를 해석할 때 package.json의 'exports' 필드를 사용합니다.
`--resolvePackageJsonImports`	`boolean`	`true` when `moduleResolution` is `node16`, `nodenext`, or `bundler`; otherwise `false`
import를 해석할 때 package.json의 'imports' 필드를 사용합니다.
`--rewriteRelativeImportExtensions`	`boolean`	`false`
상대 import 경로의 `.ts`, `.tsx`, `.mts`, `.cts` 파일 확장자를 출력 파일에서 JavaScript에 해당하는 확장자로 다시 씁니다.
`--rootDir`	`string`	Computed from the list of input files.
소스 파일 안의 루트 폴더를 지정합니다.
`--rootDirs`	`list`	Computed from the list of input files.
모듈을 해석할 때 여러 폴더를 하나로 취급할 수 있게 허용합니다.
`--skipDefaultLibCheck`	`boolean`	`false`
TypeScript에 포함된 .d.ts 파일의 타입 검사를 건너뜁니다.
`--skipLibCheck`	`boolean`	`false`
모든 .d.ts 파일의 타입 검사를 건너뜁니다.
`--sourceMap`	`boolean`	`false`
출력된 JavaScript 파일을 위한 소스 맵 파일을 생성합니다.
`--sourceRoot`	`string`
디버거가 참조 소스 코드를 찾을 루트 경로를 지정합니다.
`--stableTypeOrdering`	`boolean`	`false`
컴파일 간에 타입이 안정적이고 결정적으로 정렬되도록 보장합니다.
`--stopBuildOnErrors`	`boolean`
상류(upstream) 프로젝트의 에러 시 하류(downstream) 프로젝트 빌드를 건너뜁니다.
`--strict`	`boolean`	`true`
모든 엄격 타입 검사 옵션을 활성화합니다.
`--strictBindCallApply`	`boolean`	`true` if `strict`; `false` otherwise.
`bind`, `call`, `apply` 메서드의 인자가 원래 함수와 일치하는지 확인합니다.
`--strictBuiltinIteratorReturn`	`boolean`	`true` if `strict`; `false` otherwise.
내장 이터레이터가 any 대신 undefined의 TReturn 타입으로 인스턴스화됩니다.
`--strictFunctionTypes`	`boolean`	`true` if `strict`; `false` otherwise.
함수를 할당할 때 파라미터와 반환 값이 서브타입 호환인지 확인합니다.
`--strictNullChecks`	`boolean`	`true` if `strict`; `false` otherwise.
타입 검사 시 `null`과 `undefined`를 고려합니다.
`--strictPropertyInitialization`	`boolean`	`true` if `strict`; `false` otherwise.
선언되었지만 생성자에서 설정되지 않은 클래스 프로퍼티를 검사합니다.
`--stripInternal`	`boolean`	`false`
JSDoc 주석에 `@internal`이 있는 선언의 출력을 비활성화합니다.
`--suppressExcessPropertyErrors`	`boolean`	`false`
객체 리터럴 생성 중 초과 프로퍼티 에러 보고를 비활성화합니다.
`--suppressImplicitAnyIndexErrors`	`boolean`	`false`
인덱스 시그니처가 없는 객체를 인덱싱할 때 `noImplicitAny` 에러를 억제합니다.
`--target`	`es3`, `es5`, `es6`/`es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, `es2025`, or `esnext`	`es2023` if `module` is `node20`; `esnext` if `module` is `nodenext`; `ES5` otherwise.
출력되는 JavaScript의 JavaScript 언어 버전을 설정하고 호환되는 라이브러리 선언을 포함합니다.
`--traceResolution`	`boolean`	`false`
`moduleResolution` 과정에서 사용된 경로를 로깅합니다.
`--tsBuildInfoFile`	`string`	`.tsbuildinfo`
`.tsbuildinfo` 증분 빌드 정보를 저장할 파일입니다.
`--typeRoots`	`list`
`./node_modules/@types`처럼 동작하는 여러 폴더를 지정합니다.
`--types`	`list`
소스 파일에서 참조하지 않아도 포함할 타입 패키지 이름을 지정합니다.
`--useDefineForClassFields`	`boolean`	`true` if `target` is `ES2022` or higher, including `ESNext`; `false` otherwise.
ECMAScript 표준을 준수하는 클래스 필드를 출력합니다.
`--useUnknownInCatchVariables`	`boolean`	`true` if `strict`; `false` otherwise.
기본 catch 절 변수를 `any` 대신 `unknown`으로 지정합니다.
`--verbatimModuleSyntax`	`boolean`	`false`
type-only로 표시되지 않은 import나 export를 변환하거나 제거하지 않고, 'module' 설정에 따른 출력 파일 형식으로 그대로 쓰여지도록 보장합니다.

모든 옵션은 TSConfig Reference에서 자세히 설명됩니다.
tsconfig.json 파일을 사용하는 법을 배워 보세요.
MSBuild 프로젝트에서 작업하는 법을 배워 보세요.

더 알아보기 (Learn more)

TSConfig Reference에서 각 옵션의 전체 설명을 확인하세요.
Configuring Watch에서 watch 관련 옵션을 더 자세히 살펴보세요.