tsconfig.json 읽기

tsconfig.json은 타입 검사기(tsc)가 작업 폴더의 코드를 어떤 규칙과 환경에 맞추어 검사할지 적어 두는 설정 파일입니다. 1단원부터 복사해 써 온 과목 tsconfig.json의 열 줄이 각각 검사 규칙, 모듈 경계, 외부 선언, 그리고 Node 직접 실행과 어떻게 맞물려 있는지 알면 프로젝트에 맞게 설정을 스스로 읽고 조정할 수 있습니다.

과목 tsconfig.json의 열 가지 옵션을 세 묶음으로 나누어 하나씩 읽고, npx tsc --init이 만드는 기본 설정이나 예전 블로그 글의 설정(TS5102)과 무엇이 다른지 비교해 봅니다.

// tsconfig.json{  "compilerOptions": {    "target": "ES2022",    "strict": false,    "noEmit": true  }}// order.tsfunction discount(price) {  return price * 0.9;}const coupon: string = null;

검사 통과 — price: any, coupon: string에 null 허용

1과목 tsconfig.json 열 줄 한눈에 보기

우리가 처음부터 써 온 tsconfig.json 파일은 아래와 같습니다.

{
  "compilerOptions": {
    "strict": true,
    "target": "esnext",
    "module": "nodenext",
    "types": [],
    "noEmit": true,
    "moduleDetection": "force",
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true
  }
}

이 열 줄은 하는 일에 따라 세 묶음으로 나뉩니다.

• 엄격한 검사와 외부 선언 (strict · types · skipLibCheck)
  • "strict": true: 매개변수 타입 생략(TS7006)이나 null 혼입(TS2322) 같은 핵심 엄격 검사를 한꺼번에 켭니다(TypeScript 6.0부터 기본값이지만 눈에 보이도록 적어 둡니다).
  • "types": []: node_modules/@types 안의 패키지를 무작정 다 불러오지 않고, 여기에 적은 것(예: ["node"])만 읽습니다(TypeScript 7.0 기본값).
  • "skipLibCheck": true: 내가 짠 코드만 검사하고, 외부 패키지의 .d.ts 파일끼리 충돌하는 내부 검사는 건너뛰어 검사 속도를 높입니다.
• 모듈과 파일 경계 (target · module · moduleDetection · verbatimModuleSyntax)
  • "target": "esnext": 최신 자바스크립트 문법을 기준으로 삼습니다.
  • "module": "nodenext": Node의 최신 모듈 규칙(package.json의 "type": "module" 등)에 맞추어 import와 export를 검사합니다.
  • "moduleDetection": "force": 파일 안에 import나 export가 한 줄도 없더라도 모든 .ts 파일을 독립된 모듈로 취급합니다. 덕분에 다른 파일의 변수 이름과 겹쳐도 오류가 나지 않습니다.
  • "verbatimModuleSyntax": true: 타입을 가져올 때는 반드시 import type을 쓰도록 강제합니다(TS1484).
• Node가 .ts를 바로 실행하게 맞추기 (noEmit · erasableSyntaxOnly · allowImportingTsExtensions)
  • "noEmit": true: tsc는 타입 검사만 하고 .js 변환 파일을 만들어 내지 않습니다. 실행은 Node가 .ts 파일을 직접 맡기 때문입니다.
  • "erasableSyntaxOnly": true: 매개변수 속성(constructor(public x: number))⁠처럼 타입만 지워서는 실행할 수 없는 문법을 쓰면 TS1294로 막아, Node 직접 실행과 100% 호환되게 합니다.
  • "allowImportingTsExtensions": from "./menu.ts"처럼 경로 끝에 .ts 확장자를 적는 것을 허락합니다("noEmit": true와 짝으로 동작합니다).

2npx tsc --init 설정과 비교하기

새 폴더에서 npx tsc --init을 치면 주석이 달린 기본 tsconfig.json이 만들어집니다. 과목 설정과 견주면 다음 점이 다릅니다.

예제

실행 결과를 먼저 적어 본 뒤 펼쳐 보세요. 맞혀 보기는 점수에 들지 않습니다.

erasableSyntaxOnly와 Node 직접 실행을 모두 통과하도록 리터럴 유니언 type Size로 작성한 코드입니다.

type Size = "tall" | "grande";

const mySize: Size = "tall";
console.log(mySize);

무엇이 찍힐까요?

tall

자주 틀리는 곳

틀린 생각: 옛 블로그 글에 나온 "baseUrl": "." 같은 설정을 그대로 복사해 써도 된다.

오래된 글에 나온 tsconfig.json에는 "baseUrl": "."이나 "target": "es5", "moduleResolution": "node" 같은 옛 옵션이 흔히 들어 있습니다. TypeScript 7.0에서는 이 옛 옵션들이 완전히 삭제되어 TS5102 또는 TS5108 오류가 납니다.

맞는 규칙: TypeScript 7.0에서는 삭제된 옛 옵션을 지우고, tsconfig.json이 있는 폴더에서는 파일 이름 없이 npx tsc만 실행합니다.

틀린 생각: enum은 타입스크립트 문법이니 "erasableSyntaxOnly": true⁠에서도 그대로 쓸 수 있다.

과목 tsconfig.json의 "erasableSyntaxOnly": true⁠는 Node가 지울 수 없는 타입스크립트 전용 런타임 문법(enum, namespace, 생성자 매개변수 속성)을 미리 TS1294로 막아 줍니다.

enum Size {
  Tall,
  Grande,
}

main.ts(1,6): error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.

맞는 규칙: enum 대신 5단원에서 배운 리터럴 유니언(type Size = "tall" | "grande")⁠을 쓰면 타입만 깔끔하게 지워지고 Node에서도 바로 실행됩니다.

확인 문제

1. 과목 tsconfig.json에서 tsc가 .js 파일을 만들어 내지 않고 타입 검사만 하게 하는 옵션은 무엇인가요?

2. 다른 파일에 import나 export가 한 줄도 없어도 변수 이름이 전역으로 겹치지 않게 파일마다 독립 모듈로 만들어 주는 옵션은 무엇인가요?

3. 작업 폴더에 tsconfig.json이 있는데 터미널에서 npx tsc main.ts라고 파일 이름을 붙여 치면 어떤 문제가 생기나요?

컴퓨터에서 해 보기(선택) — 점수에 들지 않습니다. 폰으로만 보고 있다면 건너뛰세요. 작업 폴더에서 npx tsc를 실행해 보고, 일부러 npx tsc main.ts도 쳐서 TS5112 안내가 어떻게 나오는지 비교해 보세요. 다음 레슨 strict가 켜는 것들에서는 "strict": true와 noUncheckedIndexedAccess⁠를 비교합니다. 검사하고 돌리는 법은 내 컴퓨터에서 검사하고 돌리기에 있습니다.