타입스크립트 구성(tsconfig.json) 정리

TypeScript

일 년 전 / 2년 전

43K

# tsconfig.json

tsconfig.json 파일을 사용해 타입스크립트 컴파일러가 프로젝트를 JS로 변환하는 방법을 지정합니다.

JSON

L
L
L
L
L
L
L

1
2
3
4
5
6
7
{
  "files": ["node_modules/my-library/index.ts"],
  "exclude": ["node_modules", "dist"],
  "include": ["src/**/*"],
  "extends": "config/base.json",
  "compilerOptions": {}
}

tsconfig.json 예시

옵션	우선순위	설명
files	1	컴파일할 개별 파일 목록(확장자 필수!)
exclude	2	컴파일에서 제외할 파일 경로 목록
include	3	컴파일할 파일 경로 목록 `.ts`, `.tsx`, `.d.ts` 확장자 생략이 가능하며, `allowJS: true`인 경우 `.js`, `.jsx` 추가
extends	-	상속할 다른 TS 구성
compilerOptions	-	컴파일러 옵션 지정

# CompilerOptions

CompilerOptions에서 사용할 수 있는 주요 세부 옵션을 정리했습니다.

JSON

L
L
L
L
L
L
L
L
L
L
L

1
2
3
4
5
6
7
8
9
10
11
{
  "compilerOptions": {
    "target": "ES2015",
    "module": "ESNext",
    "moduleResolution": "Node",
    "jsx": "preserve",
    "strict": true,
    "esModuleInterop": true,
    "lib": ["ESNext", "DOM"]
  }
}

compilerOptions 예시

옵션	기본값	설명
target	`"ES3"`	컴파일될 ES 버전 명시.
lib	-	컴파일에서 사용할 라이브러리 지정.
module	`"CommonJS"`	모듈 시스템 지정.
moduleResolution	`"Node"`	모듈 해석 방식 지정. `"NodeNext"`는 `exports` 필드나 조건적 해석을 지원. `"bundler"`는 Vite, Webpack 등의 번들러에 맞춘 해석 방식.
esModuleInterop	`false`	ESM 모듈 방식 호환성 활성화.
isolatedModules	`false`	모든 파일을 모듈로 컴파일, `import` 혹은 `export`가 없는 경우 에러.
moduleDetection	-	모듈 감지 방식 지정. `"force"`는 모든 파일을 모듈로 강제해 전역 스코프 충돌 방지.
allowSyntheticDefaultImports	`true`	기본 내보내기(`export default`)가 없는 모듈에서 기본 가져오기 가능.
allowImportingTsExtensions	`false`	`.ts`, `.tsx` 확장자를 가진 파일을 `import` 문에서 직접 사용 가능.
baseUrl	-	모듈 해석에 사용할 기준 경로 지정.
paths	-	모듈 해석에 사용할 경로 별칭 지정.
types	-	컴파일러가 참조할 `@types` 패키지의 목록을 지정하며, 명시되지 않으면 무시.
typeRoots	`["./node_modules/@types"]`	컴파일러가 참조할 타입 선언(`.d.ts`)의 경로 목록을 지정, 명시되지 않으면 무시.
allowJS	`false`	JS 파일 컴파일 허용.
checkJs	`false`	`.js` 파일의 오류 보고 여부. `allowJS`가 `true`일 때만 유효.
jsx	`"preserve"`	JSX 지정. `"react-jsx"`는 React 17+의 새로운 JSX Transform 방식으로 컴파일.
declaration	`true`	모든 TS(JS) 파일의 타입 정보를 포함한 선언 파일(`*.d.ts`) 생성 여부.
declarationMap	`false`	`.d.ts` 파일과 함께 소스 코드 매핑 파일(`.d.ts.map`) 생성 여부. 디버깅 시 소스 코드 이동에 유용.
sourceMap	`false`	소스맵 파일 생성 여부. 디버깅 도구 등에서 JS 파일의 원본 TS 파일 표시 가능.
noEmit	`false`	컴파일 후 출력 파일(`.js`, `.d.ts` 등)을 생성하지 않음. 타입 체크만 수행할 때 사용.
skipLibCheck	`false`	`.d.ts` 파일의 타입 검사를 건너뜀. 서드파티 라이브러리 오류 무시 및 빌드 속도 향상.
strict	`false`	더 엄격한 타입 검사 활성화. 모든 엄격 옵션(`noImplicitAny`, `strictNullChecks` 등)을 포함.
noImplicitAny	`false`	(strict) 암시적 `any` 타입 검사 활성화.
noImplicitThis	`false`	(strict) 암시적 `this` 타입 검사 활성화.
strictNullChecks	`false`	(strict) 엄격한 `null`, `undefined` 타입 검사 활성화.
strictFunctionTypes	`false`	(strict) 엄격한 함수의 매개변수 타입 검사 활성화.
strictPropertyInitialization	`false`	(strict) 엄격한 클래스의 속성 초기화 검사 활성화.
strictBindCallApply	`false`	(strict) 엄격한 `bind`, `call`, `apply` 메서드의 인수 검사 활성화.
noUnusedLocals	`false`	사용되지 않는 지역 변수가 있을 경우 오류 발생.
noUnusedParameters	`false`	사용되지 않는 함수 매개변수가 있을 경우 오류 발생.
noFallthroughCasesInSwitch	`false`	논리 오류 방지를 위해 `switch` 문의 `case` 블록이 다음 `case`로 넘어가는 Fall-Through 금지.
noUncheckedIndexedAccess	`false`	객체의 인덱스 접근 시 `undefined` 가능성을 타입에 반영.
noUncheckedSideEffectImports	`false`	모듈의 부수 효과를 유발하는 `import`가 체크되지 않을 경우 오류 발생. 타입 안전성 강화(TypeScript 5.0+).
useDefineForClassFields	`false`	클래스 필드 선언 시 ECMAScript 표준(`defineProperty`) 동작을 따름. `target: "ES2022"` 이상에서 기본값 `true`.
resolveJsonModule	`false`	`.json` 파일을 모듈로 가져오기 허용.
tsBuildInfoFile	`.tsbuildinfo`	증분 컴파일(이전 컴파일 결과에서 변경된 부분만 다시 컴파일) 시 `.tsbuildinfo` 파일의 경로 지정.
verbatimModuleSyntax	`false`	ES 모듈(ECMAScript Modules) 구문을 보다 엄격하고 정확하게 해석