{{tag>[typescript compiler config tsconfig json]}}

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

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

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

<code text>
project/
├── tsconfig.json
├── tsconfig.build.json
├── src/
└── tests/
</code>

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

<code bash>
npx tsc --init
</code>

==== Basic Node.js project ====
runtime과 의존성 조건에 맞춰 ''target'', ''module'', ''moduleResolution'' 값을 조정한다.

<code json>
{
  "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"]
}
</code>

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

==== Output and language ====
  * ''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가 있을 때 출력 생성을 막는다.

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

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

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

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

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

<code json>
{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/cli" }
  ]
}
</code>

참조 대상의 설정 예:

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

<code bash>
npx tsc --build --verbose
</code>

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

===== Validation =====
<code bash>
npx tsc --project ./tsconfig.json --showConfig
npx tsc --project ./tsconfig.json --listFilesOnly
npx tsc --project ./tsconfig.json --noEmit
</code>

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

<code json>
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "tsc --project tsconfig.build.json"
  }
}
</code>

<code bash>
npm run typecheck
npm run build
</code>

===== Troubleshooting =====
==== include matches no files ====
''include'' pattern은 설정 파일 위치를 기준으로 해석한다. ''--showConfig''와 ''--listFilesOnly''로 경로와 최종 입력을 확인한다.

==== Module cannot be found ====
실제 runtime 또는 bundler에 맞는 ''module''과 ''moduleResolution'' 조합인지 확인한다. ''--traceResolution''으로 lookup 과정을 진단할 수 있다.

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

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

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

===== See Also =====
  * [[tsc:ko|tsc]]
  * [[node.js:ko|Node.js]]
  * [[https://www.typescriptlang.org/docs/handbook/tsconfig-json.html|What is a tsconfig.json]]
  * [[https://www.typescriptlang.org/tsconfig/|TSConfig Reference]]
  * [[https://www.typescriptlang.org/tsconfig/extends.html|TSConfig extends]]
  * [[https://www.typescriptlang.org/docs/handbook/project-references.html|Project References]]

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

{{indexmenu>.#1|js}}