안녕하세요! 오늘은 타입스크립트 프로젝트에서 사용되는 tsconfig.json 파일의 옵션들에 대해서 정리해보려고 합니다.

타입스크립트를 사용하는 프론트엔드 혹은 백엔드 개발자분들은 tsconfig.json 파일을 누구나 한번쯤 보고, 만져보셨을겁니다. 프로젝트를 컴파일 하는데에 중요한 역할을 담당하고 있는 설정파일이기 때문이에요.

tsconfig.json 파일을 많이 보신분들은 알겠지만, 컴파일과 관련한 타입스크립트의 옵션들은 정말 많습니다. 이를 다 외우기엔 옵션도 많고, 이 옵션이 정확히 어떤 역할을 하는거였더라? 하는 생각도 저는 많이 들더라고요.

그래서! 오늘은 핵심적인 tsconfig.json 파일의 옵션들에 대해서 정리해보겠습니다.

1. 전역 속성 📘

tsconfig.json 파일에서 전역 속성이란, 최상위에 위치하고 있는 속성을 뜻하는데요, 대표적으로 include, exclude, extends, compilerOptions 등이 있습니다. 그래서 총 4개의 전역 속성들에 대해서 알아보겠습니다.

1-1. include

include라는 단어는 포함하다라는 뜻을 가지고 있죠? include 속성은 타입스크립트 프로젝트에서 컴파일할 파일들을 지정하는 속성이며, 배열안에 여러개의 파일을 넣을 수 있습니다.

그러나 만약 프로젝트의 규모가 커져버려서 파일이 많이 생겨버렸을때는 어떻게 해야할까요? 일일히 파일을 다 적기엔 시간도 많이 들고 비효율적이죠. 이를 해결하기위해서 include 속성은 와일드 카드 패턴을 사용 할 수 있습니다.

와일드 카드 패턴에 대해서는 아래 글을 읽어보시면 많은 도움이 될겁니다. 😃 https://www.lifencoding.com/web/21?p=1

{
  "include": [
    "**/*.ts", // 모든 .ts 확장자 파일
    "**/*.tsx" // 모든 .tsx 확장자 파일
  ]
}

제가 많이 사용하는 React, Next 타입스크립트 프로젝트를 생성하면 기본적으로 include 속성에는 ts, tsx 확장자를 컴파일 하겠다라고 정의가 되어있어서, 이를 직접 건드려본적은 많이 없었던것 같네요 😛

1-2. exclude

exclude 옵션은 와일드 카드 패턴을 지원함으로써 include 옵션과 사용법은 같으나, 특징이 완전히 반대입니다. 즉 exclude는 타입스크립트 컴파일을 제외할 파일 목록을 설정하는 옵션이죠.

흔히 React, Next로 만든 프로젝트의 exclude 옵션을 살펴보시면 아래와 같이 되어있어요.

{
  "exclude": [
    "node_modules" // node_modules 폴더에 들어있는 파일들은 컴파일 제외 대상
  ]
}

1.3 extends

extends 옵션은 컴파일하고는 관계가 조금 멀다고 해야할까요? 대신 tsconfig.json 파일을 작성하면서 옵션들을 다른 JSON 파일로부터 extends 할 수 있다는 특징이 있습니다. 아래 코드를 통해서 예시를 보겠습니다.

// base.json
{
  "include": ["**/*.ts"],
  "exclude": ["node_modules"],
  "compilerOptions": {
    "allowJs": true
  }
}

// tsconfig.json
{
  "extends": "./include-exclude.json",
  "compilerOptions": {
    "target": "es5"
  }
}

위와 같이 tsconfig.json 파일에서 extends 키워드로 속성 상속시, 해당 tsconfig.json 파일에서는 상속받은 옵션을 정의할 필요없이 사용할 수 있습니다.

tsconfig.json에서는 기본적으로 include, exclude, compilerOptions.allowJs 속성을 사용중인거죠.

2. compilerOptions 🧪

compilerOptions 속성또한 위에서 설명드린 전역 속성에 들어가는 속성이지만, compilerOptions안에는 더 많은 속성들이 존재하므로 따로 섹션을 구분했습니다. 제가 느끼기로는 compilerOptions 안에 존재하는 속성들이 다른 전역 속성들의 수만큼 존재하는거 같아요.. 🤔

이 수많은 compilerOptions중에서 몇개의 중요한 속성만 알아보겠습니다!

2-1. target

흔히 타입스크립트의 컴파일 과정은 간단하게 아래와 같습니다.

• 타입스크립트 소스코드가 추상 문법트리 (Abstract Syntax Tree)로 변환된다.
• 추상 문법트리를 이용하여 타입 체크 과정
• 타입스크립트 추상 문법트리를 자바스크립트 코드로 변환한다.

위처럼 3번 과정에서 자바스크립트 코드로 변환되어서 나머지 과정이 처리되는데요, 어떤 자바스크립트 형식으로 변환될지를 결정하는 옵션이 target 옵션입니다.

자바스크립트의 ECMAScript의 종류는 여러가지가 있죠. es5, es6, es2015, es2016, esnext 등의 형식으로 적을 수 있습니다.

{
  "compilerOptions": {
    "target": "esnext"
  }
}

하지만 타입스크립트 소스코드에 target에 지정한 ECMAScript가 지원하지 않는 문법이 적힌경우, 컴파일 오류가 발생하기에 이를 유의해야합니다. 예를 들어 target을 es5로 지정을 했는데, 타입스크립트 코드에서 Promise, async-await을 사용하면 오류가 발생하므로 유의해야합니다.

보통은 ES6를 많이들 사용하는거 같아요. 😃

2-2. lib

lib 옵션은 타입스크립트 컴파일에 필요한 자바스크립트의 내장 라이브러리를 지정할 수 있는데요, 대표적인 예로 DOM API, Geolocation API, Intersection Observer API 등등 다양하게 있습니다.

만약 lib 옵션이 지정되어있지 않다면, target 옵션에 지정된 ECMAScript 버전에 따라서 컴파일이 필요한 라이브러리가 자동으로 지정됩니다.

target이 ES6로 지정된경우, ES6 컴파일에 필요한 라이브러리가 일부 기본으로 지정됩니다.

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"]
  }
}

2-3 allowJs

allowJs 옵션은 타입스크립트 프로젝트에서 자바스크립트 파일을 사용할 수 있는지를 설정할 수 있는 옵션입니다. allowJs를 true로 설정하게 되면, 타입스크립트 파일에서 자바스크립트 파일을 import 하여 사용가능합니다.

기본값은 false 입니다.

{
  "compilerOptions": {
    "allowJs": true
  }
}

2-4. jsx

jsx 옵션은 .tsx 확장자의 타입스크립트 파일을 어떻게 컴파일 할것인가를 지정하는 옵션입니다. 사용할 수 있는 옵션은 아래와 같습니다.

• react: .js 파일로 컴파일 (JSX 코드는 React.createElement() 함수 호출로 처리됨)
• react-jsx: .js 파일로 컴파일 (JSX 코드는 _jsx() 함수 호출로 처리됨)
• react-native: .js 파일로 컴파일 (JSX 코드는 유지)
• preserve: .jsx 파일로 컴파일 (JSX 코드는 유지)

{
  "compilerOptions": {
    "jsx": "preserve"
  }
}

2-5. Decorators

타입스크립트 프로젝트에서 데코레이터(@Decorator)를 사용하기 위해서는 experimentalDecorators, emitDecoratorMetadata 두개의 속성을 true로 지정해야 사용할 수 있습니다.

experimentalDecorators를 지정하면 컴파일 과정에서 데코레이터 오류가 발생하지 않고, emitDecoratorMetadata를 지정하면 런타임에서 올바르지 않게 작동하는 상황을 방지합니다.

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

2-6. module

module 옵션은 타입스크립트 프로젝트에서 사용되는 모듈 시스템을 지정하는 옵션입니다.

• CommonJS: target 옵션이 ES5 이하로 지정된경우 기본값 (require 구문으로 import 처리)
• 그외 es6, es2020, exnext (import 구문으로 import 처리)

{
  "compilerOptions": {
    "module": "CommonJS"
  }
}

2-7. typeRoots

만약 외부 라이브러리를 사용하는데, 해당 라이브러리에 타입이 정의된 파일이 없다면 .d.ts 확장자 파일을 통해서 직접 타입을 정의해야합니다.

이때 typeRoots 옵션을 통해서 해당 .d.ts 파일의 디렉토리명을 적어주면 외부 라이브러리 타입정의 파일로 인식이 가능합니다. 그러나 include 옵션에 정의된 경로가 포함되어 있다면, 안적어도 됩니다.

{
  "compilerOptions": {
    "typeRoots": ["node_modules/@types", "@types"]
  }
}

2-8. isolatedModules

isolatedModules 옵션은 타입스크립트 파일을 모듈로 정의할것을 강제화합니다.

{
  "compilerOptions": {
    "isolatedModules": true
  }
}

만약 특정 타입스크립트 파일(예: a.ts)을 만들고나서, export 키워드를 사용하지 않으면 빨간줄이 그어져 컴파일이 실패됩니다.

2-9. esModuleInterop

ES6의 모듈 내보내기시 export 혹은 export default 형식으로 내보내는데, CommonJs의 module.exports 문법이 import와 호환이 되지 않습니다.

이와 같은 문제를 해결하기 위해서 esModuleInterop 옵션을 지원합니다.

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

// 적용 전
import * as React from 'react';

// 적용 후
import React from 'react';

2-10. resolveJsonModule

resolveJsonModule 옵션은 확장자가 .json인 모듈의 import를 허용할 수 있는 옵션입니다. 기존 자바스크립트 프로젝트에서는 json import가 아무 문제없이 됐었지만, 타입스크립트에서는 기본적으로 불가능합니다.

이와 같은 문제를 마주칠시에 resolveJsonModule의 옵션을 지정해주면, json import가 가능할 뿐더러, 타입까지 자동으로 지정해줌으로써 도움이 됩니다.

{
  "compilerOptions": {
    "resolveJsonModule": true
  }
}

3. 마치며 📌

오늘은 tsconfig 옵션을 모두 정리해본 시간이 되었습니다. 도움이 많이 되셨을까요? 😛

제가 정리한 옵션들 말고도, 수많은 tsconfig 옵션들이 더 많이 있습니다!(자잘한 속성 혹은 조금 중요한 속성) 이번 글에 정리를 다 하려기엔 시간이 부족할거 같아서 제가 자주 찾아보는 속성들만 정리해봤어요. 앞으로 중요한 tsconfig 속성들은 항상 머리속에 기억해두겠습니다. 😛

이상으로 글을 마치겠습니다. 긴 글 읽어주셔서 감사합니다!