tsconfig.json 구성

tsconfig.json은 TypeScript 프로젝트의 입력 파일, compiler option, 상속, project reference를 선언하는 JSON configuration file이다.

• tsc를 파일 인수 없이 실행하면 현재 디렉터리부터 상위로 가장 가까운 tsconfig.json을 찾는다.
• –project는 사용할 설정 파일이나 그 파일이 있는 디렉터리를 명시한다.
• JSON Schema 기반 editor completion을 활용하고 tsc –showConfig와 tsc –noEmit으로 설정을 검증한다.

일반적으로 프로젝트 루트에 둔다. 용도별 설정은 기본 설정을 상속하는 별도 파일로 나눈다.

project/
├── tsconfig.json
├── tsconfig.build.json
├── src/
└── tests/

현재 설치된 TypeScript 버전의 기본 설정 파일을 생성한다.

npx tsc --init

runtime과 의존성 조건에 맞춰 target, module, moduleResolution 값을 조정한다.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "noEmitOnError": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

• files: 포함할 파일의 명시적 목록이다.
• include: 포함할 파일이나 glob pattern 목록이다.
• exclude: include가 찾은 항목에서 제외할 pattern이다. import, types, triple-slash reference 등으로 참조된 파일까지 완전히 차단하는 보안 경계는 아니다.

• target: emit할 ECMAScript language level과 기본 library declaration 범위에 영향을 준다.
• module: 생성할 module format 및 관련 해석 동작을 선택한다.
• moduleResolution: runtime 또는 bundler의 module lookup 방식과 맞춘다.
• rootDir: 입력 소스의 기준 디렉터리를 지정한다.
• outDir: 생성 파일을 기록할 디렉터리를 지정한다.
• declaration: library 배포용 .d.ts 파일을 생성한다.
• sourceMap: debugger용 source map을 생성한다.
• noEmit: type-checking만 수행하고 파일을 생성하지 않는다.
• noEmitOnError: type error가 있을 때 출력 생성을 막는다.

• strict: 현재 TypeScript 버전이 제공하는 strict 검사 묶음을 활성화한다.
• noUncheckedIndexedAccess: 선언된 index access 결과에 undefined 가능성을 추가한다.
• exactOptionalPropertyTypes: optional property를 작성된 타입 그대로 엄격하게 검사한다.
• noUnusedLocals, noUnusedParameters: 사용하지 않는 local과 parameter를 진단한다.
• forceConsistentCasingInFileNames: import path의 대소문자 불일치를 진단한다.

공통 설정을 기본 파일에 두고 환경별 파일에서 extends로 상속한다. 파생 설정에 같은 property가 있으면 상속된 값을 덮어쓴다. references는 상속되지 않으므로 필요한 설정마다 명시한다.

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "sourceMap": true
  },
  "exclude": ["tests", "dist"]
}

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

여러 package 또는 build 단위를 참조할 때 각 참조 대상에 composite를 활성화한다.

{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/cli" }
  ]
}

참조 대상의 설정 예:

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

npx tsc --build --verbose

• command-line compiler option은 설정 파일의 대응 option보다 우선한다.
• extends를 사용하면 기본 설정을 먼저 읽고 파생 설정의 property로 덮어쓴다.
• 파일을 tsc src/index.ts처럼 직접 지정하면 tsconfig.json은 무시된다.
• 실제 해석 결과는 –showConfig로 확인한다.

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

CI에서는 project-local compiler와 lockfile을 사용한다.

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "tsc --project tsconfig.build.json"
  }
}

npm run typecheck
npm run build

include pattern은 설정 파일 위치를 기준으로 해석한다. –showConfig와 –listFilesOnly로 경로와 최종 입력을 확인한다.

실제 runtime 또는 bundler에 맞는 module과 moduleResolution 조합인지 확인한다. –traceResolution으로 lookup 과정을 진단할 수 있다.

npx tsc --project tsconfig.json --traceResolution

editor가 workspace의 project-local TypeScript SDK를 사용하는지, CLI가 같은 package manager와 작업 디렉터리에서 실행되는지 확인한다.

• option의 허용값과 기본값은 TypeScript 버전에 따라 바뀔 수 있다. 현재 project-local 버전의 –help –all과 TSConfig Reference를 확인한다.
• module과 moduleResolution은 Node.js, bundler, browser 등 실제 실행 환경의 동작을 모델링해야 한다.
• JSON 파일에는 주석을 허용하는 TypeScript parser가 사용되지만 다른 일반 JSON 도구가 같은 파일을 처리하지 못할 수 있다.

• tsc
• Node.js
• What is a tsconfig.json
• TSConfig Reference
• TSConfig extends
• Project References

• codex:: 2026-08-04 tsconfig.json의 주요 필드, 상속, project reference, precedence, 검증 workflow를 정리함.