TypeScript와 tsconfig.json
이 문서에서는 TypeScript와 tsconfig.json에 대해 설명합니다.
TypeScript의 기본 역할부터, 구체적인 예시와 함께 tsconfig.json이 프로젝트 내에서 어떻게 동작하는지 설명합니다.
YouTube Video
TypeScript와 tsconfig.json
TypeScript는 '타입이 있는 JavaScript'입니다. 하지만 실제 프로젝트에서 TypeScript를 효과적으로 활용하려면 tsconfig.json을 올바르게 이해하고 의도적으로 설정하는 것이 필수입니다.
왜 TypeScript가 필요할까요?
먼저, TypeScript를 사용하는 주요 이유는 **'실행 전에 실수를 잡아낼 수 있다'**는 점입니다.
1function add(a: number, b: number): number {
2 return a + b;
3}
4
5add(1, "2");이 코드는 JavaScript에서는 실행 시점까지 에러가 발생하지 않지만, TypeScript에서는 컴파일 타임에 타입 에러가 발생합니다.
이러한 '조기 발견'은 개발 효율성과 품질을 크게 향상시킵니다.
TypeScript는 어떻게 실행될까요?
원칙적으로 TypeScript는 그대로 실행될 수 없습니다. tsc(TypeScript Compiler)를 사용하여 JavaScript로 변환해야 합니다..
1npm install -D typescript
2npx tsc --init- 이 작업을 수행하면
tsconfig.json이 생성되어, TypeScript 프로젝트의 동작을 정의하는 중심 파일이 됩니다.
tsconfig.json의 역할은 무엇인가요?
tsconfig.json은 **'어떤 파일을', '어떤 규칙으로', '어떻게 변환할지'**를 결정하는 설정 파일입니다. 처음에는 복잡해 보일 수 있지만, 실제로 중요한 설정은 몇 가지에 불과합니다.
1{
2 "compilerOptions": {
3 "target": "ES2020",
4 "module": "ESNext",
5 "strict": true
6 }
7}- 이 몇 가지 설정만으로도 모던하고 안전한 TypeScript 개발이 가능합니다.
target: 출력할 JavaScript 버전
target은 변환 후 JavaScript의 명세 수준을 결정합니다.
1"target": "ES2020"이렇게 하면 TypeScript는 ES2020에 해당하는 JavaScript를 출력합니다. 구형 환경에서는 ES5를, 최신 환경만 지원한다면 ES2022 등으로 선택하세요.
ESNext를 지정할 때
1"target": "ESNext"-
ESNext는 최신 JavaScript 문법을 그대로 출력하겠다는 의미입니다. TypeScript는 해당 문법을 변환하지 않고, Node.js나 브라우저와 같은 런타임 환경에서 처리하도록 남겨둡니다. -
따라서, 최신 Node.js만을 대상으로 하거나 Babel, 번들러 등으로 따로 트랜스파일할 경우
ESNext가 적합합니다. 반면에 실행 환경이 최신 문법을 지원하지 않을 경우 런타임 에러가 발생할 수 있으므로 주의가 필요합니다.
module: 모듈 형식 지정
module은 모듈 포맷을 지정합니다.
1"module": "ESNext"- 프론트엔드와 최신 Node.js 환경에서는
ESNext가 표준입니다. - CommonJS가 필요한 경우에만
"CommonJS"를 선택하세요.
strict: 타입 안전성 극대화
strict는 TypeScript의 안전성을 극대화하기 위한 스위치입니다.
1"strict": true- 이 옵션을 켜면 애매한 타입과 잠재적인 버그를 철저하게 잡아냅니다.
strict 모드와 implicit any
strict를 활성화하면, 타입을 추론할 수 없는 변수에 대해 TypeScript가 에러로 처리합니다.
1function printValue(value) {
2 console.log(value);
3}- 이 변수
value는 선언 시 타입 정보가 없기 때문에 TypeScript가 타입을 알 수 없습니다. 결과적으로 컴파일러는 암시적으로any를 사용하게 되고, 이는strict모드에서 경고(오류)가 발생합니다.
1function printValue(value: number) {
2 console.log(value);
3}- 이렇게 타입을 명시적으로 지정하면 '이 변수는 오직 숫자만 취급한다'고 TypeScript가 이해할 수 있습니다. TypeScript에서 더 중요한 것은 타입을 생략할 수 있는 것보다 타입이 명확하게 결정될 수 있는 것입니다.
include/exclude: 컴파일할 파일 제어
tsconfig.json에서는 어떤 파일을 포함할지와 어떤 파일을 제외할지 컴파일 범위를 지정할 수 있습니다.
1{
2 "include": ["src"],
3 "exclude": ["node_modules"]
4}- 이렇게 하면
src폴더 이하의 파일만 TypeScript가 관리하게 됩니다. exclude에 지정된node_modules는include에 포함된 경로 내에 있어도 컴파일에서 제외됩니다.
outDir: 출력 디렉터리 지정
outDir을 지정하면 빌드 결과물이 저장될 위치를 관리할 수 있습니다.
1"outDir": "dist"- 이렇게 하면, 모든 컴파일된 결과가
dist폴더에 출력됩니다. 실제로는 소스 코드와 빌드 산출물을 분리하는 것이 표준입니다.
rootDir: 소스 디렉터리 지정
rootDir은 TypeScript가 소스 코드의 루트로 취급할 디렉터리를 지정합니다.
1"rootDir": "src"-
이 설정을 통해 TypeScript는
src를 기준으로 디렉터리 구조를 그대로 유지하여 파일을 출력합니다. 예를 들어,src/index.ts는dist/index.js로 출력됩니다. -
rootDir에 지정된 디렉터리 구조가outDir에 복사됩니다.
esModuleInterop: CommonJS와 ES 모듈 간 호환
다음으로 esModuleInterop을 살펴보겠습니다.
1"esModuleInterop": true- 이 옵션을 활성화하면
import문법으로 CommonJS 모듈을 안전하게 사용할 수 있습니다.
1import fs from "fs";- 이 설정은 Node.js를 사용할 때 거의 필수적입니다.
noImplicitAny: 암시적 'any' 타입 금지
tsconfig.json에서 타입 검사 강화를 설정하는 것도 중요합니다.
1"noImplicitAny": true- 이렇게 하면 암시적
any타입을 금지할 수 있습니다. 이 설정으로 타입 명시를 깜빡한 부분을 확실히 발견할 수 있습니다.
사용하지 않는 코드 감지 설정
사용하지 않는 코드를 감지하는 설정 역시 유지보수성을 높이는 데 도움이 됩니다.
1"noUnusedLocals": true,
2"noUnusedParameters": true- 이렇게 하면 불필요한 변수와 인자가 바로 경고로 표시됩니다.
lib: 사용할 수 있는 내장 API 정의
lib는 TypeScript가 존재한다고 가정하는 표준 API를 지정하는 설정입니다.
1"lib": ["ES2020", "DOM"]- 이 설정을 통해 다음과 같은 타입이 사용 가능해집니다:.
ES2020을 지정하면Promise,Map,Set등 최신 기능을 사용할 수 있습니다.DOM을 포함하면document,window,HTMLElement등 브라우저 API도 사용할 수 있습니다.
프론트엔드에서는 DOM을 포함하고, Node.js 프로젝트에서는 불필요한 글로벌 타입이 포함되는 것을 방지하기 위해 DOM을 제거하세요.
moduleResolution: 모듈 탐색 규칙
moduleResolution은 import 구문에서 명시된 모듈이 어떻게 해석될지를 결정합니다.
1"moduleResolution": "Node"주요 옵션은 아래와 같습니다:.
Node를 지정하면, Node.js 모듈 해석 규칙이 적용됩니다.Classic은 이전의 TypeScript 전용 방식이지만, 최근에는 거의 사용되지 않습니다.
Node.js 또는 번들러를 사용하는 환경에서는 Node를 명시적으로 지정하는 것이 안전합니다.
최소한의 실전용 tsconfig.json
지금까지 설명한 내용을 바탕으로, 최소한의 실전용 tsconfig.json은 다음과 같습니다:.
1{
2 "compilerOptions": {
3 "target": "ES2020",
4 "module": "ESNext",
5 "moduleResolution": "Node",
6 "lib": ["ES2020", "DOM"],
7 "strict": true,
8 "rootDir": "src",
9 "outDir": "dist",
10 "esModuleInterop": true,
11 "noImplicitAny": true,
12 "noUnusedLocals": true,
13 "noUnusedParameters": true
14 },
15 "include": ["src"]
16}이 설정은 프론트엔드와 Node.js 프로젝트 모두에 안전한 밑바탕을 제공합니다.
요약: tsconfig.json은 '규칙서'입니다
tsconfig.json은 단순한 설정 파일이 아니라, **프로젝트 전체에 적용되는 '규칙서'**입니다. tsconfig.json을 통해 다음과 같은 중요한 정책들을 명확하게 정할 수 있습니다:.
- 타입 안전성 수준.
- 팀의 코딩 규약.
- 미래 버그 예방.
tsconfig.json을 이해하면, 단순히 TypeScript 코드를 작성할 뿐 아니라, 안전하게 TypeScript를 사용하는 프로젝트 설계도 가능해집니다..
위의 기사를 보면서 Visual Studio Code를 사용해 우리 유튜브 채널에서 함께 따라할 수 있습니다. 유튜브 채널도 확인해 주세요.