🛠️ 타입스크립트 환경 설정 완전 정복 - tsconfig.json 제대로 알기 (Strict 모드 중심)

TypeScript 프로젝트를 시작할 때 가장 먼저 등장하는 파일, 바로 tsconfig.json입니다.
이 설정 파일을 제대로 이해하지 못하면 타입스크립트의 진정한 힘을 활용하지 못하고,
에러를 감추거나 불필요한 경고에 시달리게 됩니다.

이번 글에서는 tsconfig.json의 핵심 옵션들, 특히 Strict 모드 중심으로 실무에 필요한 설정들을 차근차근 정리해보겠습니다.

---

🎯 tsconfig.json이란?

• TypeScript 컴파일러에게 “이 프로젝트는 이렇게 컴파일 해줘!”라고 알려주는 설정 파일
• tsc 명령어 실행 시 이 파일을 기준으로 .ts 파일을 .js로 변환
• 위치: 프로젝트 루트(/)에 생성됨

 

npx tsc --init​

실행하면 아래처럼 기본 tsconfig.json이 생성됩니다.

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

 

 

---

🔒 Strict 모드란?

"strict": true

"나는 엄격한 타입 검사 원칙을 지킬게!"
이 옵션은 여러 개의 세부 옵션을 한 번에 켜주는 상위 설정입니다.

포함되는 하위 옵션들:

옵션	설명
strictNullChecks	null, undefined를 명시적으로 처리하도록 강제
noImplicitAny	타입이 자동으로 any로 추론되는 것을 막음
strictFunctionTypes	함수 파라미터의 타입 일치를 엄격하게 검사
strictBindCallApply	bind, call, apply 사용 시 인자 타입을 검사
alwaysStrict	컴파일된 JS에 "use strict" 자동 삽입
strictPropertyInitialization	클래스 프로퍼티 초기화를 필수로 강제
useUnknownInCatchVariables	catch 블록의 에러 타입을 any 대신 unknown으로 지정

Strict 모드는 실무에 반드시 켜야 합니다.
하지만 처음엔 너무 많은 에러가 나서 당황할 수 있어요. 그래서 아래처럼 점진적으로 켜는 전략도 가능해요:

"strict": false,
"noImplicitAny": true,
"strictNullChecks": true,

---

⚙️ 실무에서 꼭 확인해야 할 주요 compilerOptions

옵션	설명
target	변환할 JavaScript 버전 (ex: es5, es2015, esnext)
module	모듈 시스템 지정 (ex: commonjs, esnext)
moduleResolution	모듈 찾는 방식 (node 권장)
baseUrl, paths	모듈 경로 별칭 설정 (@/components 등)
outDir	컴파일된 JS 파일이 생성될 폴더
rootDir	소스 파일이 있는 루트 경로
include, exclude	컴파일 포함/제외할 파일 패턴 지정

예시:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"]
    },
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

 

---

💡 실무 적용 팁

1. 처음부터 "strict": true는 부담스럽다면, noImplicitAny, strictNullChecks만 켜고 시작해도 OK
2. esModuleInterop은 대부분의 JS 라이브러리와 호환을 위해 true 추천
3. baseUrl, paths를 활용하면 import 경로가 깔끔해짐
4. skipLibCheck: true는 외부 라이브러리 타입 검사 생략 – 빌드 속도 개선에 도움

---

📦 마무리: 추천 설정 Preset

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"]
    },
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

---

✨ 다음 글 예고

👉 [TypeScript 개발 환경 세팅 (VSCode + ESLint + Prettier)]