타입스크립트 프로젝트의 핵심 설정 파일인
tsconfig.json을 제대로 활용하면 개발 효율과 코드의 안정성을 동시에 잡을 수 있습니다. 실무에서 가장 자주 쓰이고 중요한 옵션들을 예제와 함께 정리했습니다.
🚀 한눈에 보는 tsconfig.json 예시
아래는 실무에서 흔히 쓰이는 주요 옵션들을 모은 예시 설정입니다.
{
"compilerOptions": {
"target": "ESNext", // 최신 자바스크립트 버전으로 컴파일
"lib": ["dom", "dom.iterable", "esnext"], // 사용 가능한 내장 API 목록 (브라우저 환경 등)
"module": "CommonJS", // 생성될 자바스크립트의 모듈 시스템 (CommonJS, NodeNext 등)
"outDir": "dist", // 컴파일된 파일들이 저장될 위치
"strict": true, // 모든 엄격한 타입 검사 옵션 활성화
"noEmit": true, // 변환된 JS 파일을 생성하지 않음 (타입 체크 전용)
"jsx": "react-jsx", // JSX 문법 처리 방식 (React 최신 버전용)
"strictNullChecks": true, // null과 undefined 엄격하게 구분
"moduleDetection": "force", // 모든 파일을 격리된 모듈로 취급 (전역 오염 방지)
"resolveJsonModule": true, // JSON 파일을 직접 import 가능하게 허용
"isolatedModules": true, // 각 파일을 독립된 모듈로 컴파일 (빌드 도구 호환성)
"skipLibCheck": true, // 라이브러리 파일(*.d.ts)의 타입 검사 건너뛰기
"esModuleInterop": true, // CommonJS 모듈을 ES6 문법으로 자연스럽게 import
"incremental": true, // 변경된 부분만 컴파일하여 빌드 속도 향상
"plugins": [{ "name": "next" }], // 프레임워크(Next.js 등) 전용 플러그인
"paths": { // 경로 별칭 설정
"@/*": ["./src/*"]
}
},
"ts-node": {
"esm": true // ts-node에서 ESM 모듈 형식 사용 설정
},
"include": ["src"] // 컴파일 대상 폴더 지정
"exclude": ["node_modules"] // 컴파일에서 제외할 폴더
}| 옵션 | 기본값 (Default) | 참고 사항 |
|---|---|---|
| target | ES3 | 아주 보수적이죠? 그래서 보통 ES6나 ESNext로 명시합니다. |
| module | target에 따라 다름 | target이 ES3~5면 CommonJS, ES6 이상이면 ESNext가 기본인 경우가 많습니다. |
| outDir | undefined | 명시하지 않으면 .ts 파일이 있는 위치에 .js가 생성됩니다. |
| strict | false | 가장 중요한 옵션입니다. 안정성을 위해 반드시 true를 권장합니다. |
| strictNullChecks | false | strict: true를 설정하면 자동으로 true가 됩니다. |
| moduleDetection | auto | 기본은 auto지만, 현대적인 프로젝트에서는 force가 안전합니다. |
| skipLibCheck | false | 외부 라이브러리 에러까지 잡으려다 빌드가 느려지곤 해서 보통 true로 씁니다. |
| esModuleInterop | false | import React from 'react' 같은 문법을 쓰려면 true가 필수입니다. |
| incremental | false | 빌드 속도를 위해 true로 두는 것이 유리합니다. |
| lib | target에 따라 다름 | 브라우저 API(dom) 등을 쓸지 결정합니다. |
| noEmit | false | 결과물을 생성하지 않고 타입 체크만 할 때 true로 둡니다. |
| resolveJsonModule | false | JSON 파일을 직접 import 하려면 true로 켜주세요. |
| isolatedModules | false | Vite 등 최신 빌드 도구를 쓴다면 안전을 위해 true를 권장합니다. |
| jsx | undefined | React 등 JSX 문법 처리 방식을 결정합니다 (예: react-jsx). |
| exclude | [node_modules] | 컴파일에서 제외할 폴더를 지정해 빌드 성능을 높입니다. |
📘 핵심 옵션 상세 설명
1. 기본 설정 (Project Structure)
target: 타입스크립트 코드를 어떤 버전의 자바스크립트로 변환할지 정합니다. ESNext는 현재 환경에서 지원하는 가장 최신의 사양을 의미합니다.module: 자바스크립트 파일 간에 코드를 주고받는 방식을 정합니다. Node.js 백엔드 환경에서는 주로 CommonJS를, 최신 웹 번들러 환경에서는 ESNext를 사용합니다.outDir: tsc 명령어로 컴파일했을 때 자바스크립트 결과물들이 저장될 폴더를 지정합니다. 주로 dist나 build 폴더를 사용합니다.include: 타입스크립트가 컴파일할 파일의 범위를 정합니다. ["src"]로 설정하면 src 폴더 안의 파일들만 관리하게 되어 훨씬 깔끔합니다.exclude: 컴파일 과정에서 명시적으로 제외할 폴더를 지정합니다. 보통node_modules나dist폴더를 제외하여 컴파일 성능을 최적화합니다.
2. 타입 검사 (Checking & Emit)
strict: 타입스크립트의 정수입니다.true로 설정하면 모든 엄격한 타입 체크 기능을 켭니다. 새로 시작하는 프로젝트라면 반드시true로 설정하는 것을 권장합니다.strictNullChecks:null이나undefined값을 다룰 때 발생할 수 있는 런타임 에러를 방지합니다.noEmit: 타입스크립트가 자바스크립트 결과물을 직접 생성(Emit)하지 않도록 합니다.최근에는 Vite나 Next.js(SWC)처럼 다른 도구가 빌드를 전담하므로, 타입스크립트는 "오직 타입 체크"만 수행하도록 이 옵션을 켜두는 경우가 많습니다.
skipLibCheck:node_modules에 있는 라이브러리 타입 정의 파일들의 검사를 생략합니다.
TIP
버전이 다른 여러 라이브러리가 같은 타입 이름을 다르게 정의해서 발생하는 충돌(특히 20버전 이상 대응 시)을 해결할 때 매우 유용합니다.
3. 모듈 및 라이브러리 설정 (Modules & Libs)
lib: 타입스크립트가 어떤 환경의 내장 함수(API)들을 알고 있는지 정합니다. 브라우저용 앱이라면["dom", "dom.iterable", "esnext"]처럼 설정하여window,document같은 인터페이스를 사용할 수 있게 합니다.moduleDetection: "force": 파일 내부에import나export가 없어도 타입스크립트가 이를 독립된 모듈로 인식하게 만듭니다. 전역 공간이 더러워지는 것을 방지하는 아주 깔끔한 옵션입니다.resolveJsonModule:tsconfig.json파일을 한 컴파일 단위 내에서 직접import할 수 있게 해줍니다. 설정 정보나 상수 데이터를 다룰 때 매우 유용합니다.isolatedModules: 모든 파일을 각각의 독립된 모듈로 강제합니다. 현대적인 빌드 도구(SWC, esbuild)는 파일을 하나씩 따로 변환하기 때문에, 이 옵션을 켜두어야 도구들이 안전하게 코드를 처리할 수 있습니다.
4. 개발 환경 유틸리티
jsx: JSX 문법을 최종 결과물에서 어떻게 표현할지 결정합니다. 최신React프로젝트라면"react-jsx"를 사용하여 별도의import React없이도 JSX를 사용할 수 있게 합니다.plugins:Next.js와 같은 프레임워크 전용 플러그인을 설정합니다. 예를 들어Next.js플러그인은 컴포넌트 내에서 타입 체크를 더 정확하게 도와줍니다.ts-node: 타입스크립트 파일을 컴파일 없이 바로 실행할 때 필요한 설정입니다. "esm": true 옵션은 최신 모듈 시스템을 원활하게 사용하게 해줍니다.paths:../../shared/ui/Button같은 지저분한 경로를@/shared/ui/Button으로 바꿔줍니다. 코드 가독성이 획기적으로 좋아집니다.esModuleInterop:import * as React from 'react'대신import React from 'react'처럼 더 현대적인 방식으로 라이브러리를 가져올 수 있게 도와줍니다.
🔍 잠깐! "번들러(Bundler)"란 무엇인가요?
컴파일 옵션을 설명할 때 자주 등장하는 번들러는 수많은 자바스크립트 파일, CSS, 이미지 등 프로젝트의 자원들을 하나의 파일(또는 소수의 파일)로 묶어주는 도구입니다.
- 대표 도구: Vite, Webpack, esbuild, Rollup
- 필요한 이유: 브라우저가 수많은 파일을 개별적으로 요청하면 로딩 속도가 느려지기 때문에, 이를 최적화해서 하나로 합치고 코드를 압축하는 역할을 합니다. 최근 타입스크립트 설정(
moduleResolution: "bundler")은 바로 이 도구들과의 호환성을 맞추기 위한 것입니다.
🔥 2026년 선호하는 최신 트렌드
최근 Vite, Next.js, Bun과 같은 현대적인 도구들을 사용하는 프로젝트에서는 다음과 같은 설정들이 표준처럼 자리 잡고 있습니다.
-
moduleResolution: "bundler"
예전에는node를 주로 썼지만, 이제는Vite나Webpack같은 번들러 환경에 최적화된"bundler"옵션을 사용합니다. 이는 현대적인 패키지들이 제공하는exports필드를 정확하게 해석해 줍니다. -
verbatimModuleSyntax: true
기존의importsNotUsedAsValues를 대체하는 최신 옵션입니다.import type을 명확히 구분하여 컴파일된 자바스크립트에 불필요한 코드가 남지 않도록 엄격하게 관리하며, 번들러와의 호환성이 매우 좋습니다. -
isolatedModules: true
각 파일을 독립적으로 컴파일할 수 있음을 보장합니다. 이는SWC나esbuild처럼 타입 정보를 사용하지 않고 빠르게 트랜스파일하는 도구들을 쓸 때 필수적인 설정입니다. -
noUnusedLocals & noUnusedParameters
사용하지 않는 변수나 매개변수가 있을 때 에러를 발생시킵니다. 코드의 청결도를 유지하는 데 매우 효과적이라 많은 팀에서 기본적으로 활성화하는 추세입니다.
💡 마치며
tsconfig.json은 단순히 설정을 나열하는 곳이 아니라, 우리 프로젝트의 품질 가이드라인을 정하는 곳입니다. 특히 strictNullChecks나 moduleDetection 같은 옵션을 적극적으로 활용하여 타입 안정성과 모듈 일관성을 확보하면, 팀 전체의 개발 경험이 훨씬 견고해지고 예측 가능한 코드베이스를 유지할 수 있습니다.
📚 공식 출처 및 참고 자료
이 글은 다음의 공식 자료와 최신 생태계 권장 사항을 바탕으로 작성되었습니다.
