[TYPESCRIPT] tsconfig.json 완벽 가이드 - TypeScript 프로젝트 설정의 모든 것

TypeScript 프로젝트를 시작하면 반드시 마주하게 되는 파일이 tsconfig.json입니다. 이 파일은 컴파일러 옵션, 빌드 경로, 모듈 시스템 등 TypeScript 프로젝트의 핵심 동작을 정의합니다. 각 옵션의 의미를 설명하고, 실무에서 자주 사용하는 설정 예시를 정리해 보겠습니다.

 

tsconfig.json이란?

tsconfig.json은 TypeScript 컴파일러(tsc)가 어떤 방식으로 프로젝트를 해석하고 변환할지 결정하는 설정 파일입니다.

주요 기능은 아래와 같습니다.

• TypeScript → JavaScript 변환 규칙 정의
• 컴파일할 파일의 범위 지정
• ECMAScript 버전, 모듈 형식 선택
• Strict 모드 적용 여부
• 경로 alias 설정
• Node/Browser 환경 설정

이 파일 하나로 프로젝트의 동작이 완전히 달라질 수 있으므로, 반드시 정확히 이해하고 설정해야 합니다.

 

tsconfig.json 생성

아래 명령으로 기본 설정 파일을 생성할 수 있습니다.

npx tsc --init

생성된 파일은 주석 포함 100줄 이상의 옵션이 있지만, 실무에서는 그중 핵심만 사용합니다.

 

실무에서 자주 사용하는 핵심 옵션

1. target

컴파일된 JavaScript 코드가 어떤 ECMAScript 버전을 사용할지 결정합니다.

• "ES5" — 가장 호환성 높음 (옛 브라우저용)
• "ES2017" ~ "ES2022" — 최신 문법 사용 가능
• "ESNext" — 최신 스펙을 그대로 사용

"target": "ES2020"

Node.js 개발이라면 ES2020 이상 사용을 권장합니다.

 

2. module

JavaScript 모듈 시스템을 지정합니다.

• "commonjs" — Node.js 기본 모듈 방식
• "ESNext" — ES Module 방식 (import/export)

"module": "commonjs"

Node.js 18 이상에서는 ESM이 안정적이지만, 실무에서는 아직도 commonjs가 널리 사용됩니다.

 

3. rootDir / outDir

TypeScript 파일의 입력/출력 디렉터리를 지정합니다.

"rootDir": "./src",
"outDir": "./dist"

컴파일 시 src 안의 모든 파일을 dist에 변환하여 저장합니다.

 

4. strict

TypeScript의 타입 검사 수준을 결정하는 중요한 옵션입니다.

"strict": true

true로 설정하면 아래 기능이 모두 활성화됩니다.

• null/undefined 체크 강화
• 암묵적 any 금지
• 정확한 타입 추론
• 함수 반환 타입 체크

실무에서는 유지보수성과 품질 향상을 위해 반드시 strict: true를 권장합니다.

 

5. esModuleInterop

CommonJS 모듈과 ES 모듈을 혼합하여 사용할 수 있게 하는 옵션입니다.

"esModuleInterop": true

예를 들어 이것이 없으면 다음처럼 작성해야 합니다:

import * as express from 'express';

하지만 esModuleInterop: true이면 이렇게 쓸 수 있습니다:

import express from 'express';

Node.js + TypeScript 개발에서는 사실상 필수 옵션입니다.

 

6. resolveJsonModule

TypeScript에서 JSON 파일을 import할 수 있게 해줍니다.

"resolveJsonModule": true

환경 설정 등을 JSON으로 관리할 때 유용합니다.

 

7. baseUrl과 paths (Alias 설정)

프로젝트에서 경로 alias를 만들어 가독성과 유지보수성을 높일 수 있습니다.

"baseUrl": "./",
"paths": {
  "@/*": ["src/*"]
}

이제 다음과 같이 경로를 단축할 수 있습니다:

import { UserService } from "@/services/UserService";

(Node 런타임에서는 tsconfig-paths 또는 module-alias 패키지가 필요할 수 있습니다.)

 

include / exclude

어떤 파일을 컴파일할지 지정합니다.

"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]

불필요한 파일이 빌드 대상에 포함되지 않도록 주의해야 합니다.

 

moduleResolution

모듈을 찾을 때 어떤 방식으로 탐색할지 결정합니다.

• "node" — Node.js의 require 방식 (기본)
• "bundler" — Webpack, Vite 환경에서 사용

"moduleResolution": "node"

Node.js 환경이라면 기본값인 node를 그대로 사용하면 됩니다.

 

실무에서 가장 많이 사용하는 tsconfig.json 예시

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

이 설정은 Node.js 백엔드(NestJS, Express)부터 프론트엔드(React, Vue)까지 대부분의 실무 프로젝트에서 공통적으로 사용되는 구성입니다.

 

자주 발생하는 문제와 해결법

1. import 경로 alias가 적용되지 않음

→ 실행 시 ts-node 대신 아래 패키지가 필요할 수 있습니다.

pnpm install -D tsconfig-paths

실행 예:

node -r ts-node/register -r tsconfig-paths/register src/main.ts

2. CommonJS/ESM 충돌

→ module과 moduleResolution 설정이 Node 버전과 맞지 않을 수 있습니다.

3. JSON import 오류

"resolveJsonModule": true

4. @types/node 설치 필요

pnpm install -D @types/node

 

 

tsconfig.json은 단순한 설정 파일이지만, 프로젝트 구조와 컴파일 방식 전체를 제어하는 “TypeScript 프로젝트의 심장”입니다. 정확히 이해하고 설정하면 안정적인 빌드 환경을 구축할 수 있으며, 반대로 잘못 설정하면 모듈 충돌이나 타입 오류가 지속적으로 발생할 수 있습니다.

이번 가이드가 TypeScript 개발 환경을 설계하고 유지보수하는 데 큰 도움이 되길 바랍니다.