TypeScript, tsconfig.json 주요 설정

Programming language/Typescript

TypeScript, tsconfig.json 주요 설정

iKay 2021. 1. 7. 03:49

서론

TypeScript를 더 잘 사용하기 위해 컴파일 하기 위한 설정, 동작방식을 정의하는 tsconfig를 어느 정도 이해할 필요가 있다고 생각한다. Node.js 프로젝트에 TypeScript를 설정하기 위해서 공식문서를 참고하는 것이 가장 정확하겠지만 정보의 양이 방대해서 주요한 몇몇 설정만 정리해 보고자 한다. 앞으로 지식과 경험이 더 넓어지면 내용을 계속 덧붙여 나갈 계획이다. 자세한 설명은 당연히 공식문서를 참조하는 것이 좋겠다.

tsconfig.json을 작성하는 것은 옳고 그름의 문제가 아니다. 프로젝트 마다, 팀마다 각각 상황에 맞게 설정하면 되는 것이기 때문에 무조건 따라야 하는 설정은 없다. 잘 모르겠으면 권장하는대로, 기본값대로 사용해도 될 것이다. 다만, 각 프로젝트 마다 성격에 맞게 사용하기 위해, "어떤 설정이 있었고, 이 설정이 무엇을 뜻했던 것 같다." 정도는 알고 있는 것이 좋을 것 같아서 정리해 보고자 한다. 만약 TypeScript 설정에 당장은 관심이 없고 잘은 모르겠지만 TypeScript를 사용해야 하는 상황이라면 공식 문서에서 추천해주는 대로 extends 해서 일단 사용하는 것도 큰 노력을 사용하지 않는 좋은 방법일 것이다.

TypeScript가 컴파일 될 때, 보통 TypeScript 프로젝트의 root에 tsconfig.json 파일이 위치하는데, compile하기 위한 소스코드의 위치, compile 옵션을 이곳에 json 파일로 나타내면 된다. 만약, tsc 명령어로 compile 하는데 input file이 주어지지 않으면 현재 디렉토리에서 부터 부모 디렉토리 체인으로 거슬러 올라가면서 tsconfig.json 파일을 찾는다. 반대로, tsc 명령어에 input file이 주어지면 tsconfig.json 파일을 검색하지 않는다.

설정들에 대한 설명들을 레퍼런스 문서에서 나누고 있는 큰 범주대로 나누었다. 공식문서에는 알파벳 순으로 설정들을 나열하고 있지만 여기서는 개인적으로 중요하다고 생각되는 것을들 먼저 나열할 수도 있다.

1. File Inclusion

TypeScript가 compile에 포함하거나 제거할 파일들을 명시하고, compile 하기 위해 참조해야하는 설정이 있는 파일들을 설정한다.

include, exclude

컴파일 할때 포함하거나 제외할 filenames 배열이나 패턴을 명시한다. 패턴을 명시할 때 glob pattern을 사용하고, filenames의 path는 tsconfig.json 이 있는 곳으로 부터 상대경로에 있는 것들이다.

주의할 점은 exclude는 include와 함께 동작하면서 include 될 것을 exclude 시키는 것이지, code에 있는 것을 제외시키는 것은 아니다.

include는 defalut로 다음과 같은 값을 갖는다.

["**/*"]

exclude는 default로 다음과 같은 값을 갖는다.

// 만약 outDir이 명시되어 있으면 그것도 default에 포함된다.
["node_modules", "bower_components", "jspm_packages"]

예

{
  "include": ["src/**/*", "tests/**/*"],
  "exclude": ["tests/modules/*"]
}

extends

상속받을 다른 base file을 명시한다. 설정들은 base file이 우선 load 되고, 상속하는 file이 override 하게 동작한다. 팀 내에서 이런식으로 tsconfig.json 파일을 npm으로 관리해도 좋을 것 같다.

files

include 시킬 파일들을 개별적으로 포함시킨다. 보통의 경우 include만으로 해결될 것이기 때문에 아마 잘 사용되지 않을 것 같다.

예

{
  "compilerOptions": {},
  "files": [
    "core.ts",
    "sys.ts",
    "types.ts",
    "scanner.ts",
    "parser.ts",
    "utilities.ts",
    "binder.ts",
    "checker.ts",
    "tsc.ts"
  ]
}

2. Compiler Options

Project Options

TypeScript가 compile 되는 방식, 동작하는 방식을 설정한다.

사용할 수 있는 많은 옵션들이 있다. 중요하다고 생각되는 것들, 자주 사용될 것 같은 것 위주로 정리해 보고자 한다.

lib

lib는 target과 함께 사용되기도 해서 target과 함께 구분해가면서 봐두면 좋다고 생각한다.

lib는 타입스크립트는 built-in JS API(예, Math)와 브라우저 환경(예, document) 등에서 사용할 수 있는 타입을 기본적으로 제공한다. JS 버전마다 사용할 수 있는 문법이나 API 등이 조금씩 다른다. 보통 계속 추가되면서 하위호환을 유지하는 편이다. 이런 것들 중 target에 설정한 버전에 부합하는 API 등의 타입을 사용할 수 있게 해준다.

예를 들어,

target에 ES6라고 설정한 경우, ES6+부터 Map이라는 것을 JS에서 네이티브하게 사용할 수 있기 때문에 Map을 사용하기 위한 타입을 제공한다.
백엔드 개발을 하는 경우 브라우저 환경의 개발환경을 설정할 필요가 없다. 그래서 이런 경우, "dom" 타입을 설정할 필요가 없다.
polyfill을 사용하거나, nodeJS가 native 적으로 ECMAScript 버전을 일부 지원하는 경우 target 버전과 완전히 동일하지 않아도 liib로 선택적으로 버전을 올려서 사용할 수 있다.

타입이 어떻게 설정될까 궁금해서 조금 찾아보다가, TypeScript의 lib에 대한 소스코드에서 동작하는 방식을 추론할 수 있었는데, 소스코드에서 볼 수 있듯이 상위버전은 하위 버전을 포함해서 사용할 수 있게 되고, lib.esXXXX.d.ts는 ECMAScript의 XXXX 버전에 해당하는 모든 것을 포함한다는 것도 볼 수 있다.

// 예, lib.es2019.d.ts 파일의 소스코드

/// <reference no-default-lib="true"/>


/// <reference lib="es2018" />
/// <reference lib="es2019.array" />
/// <reference lib="es2019.object" />
/// <reference lib="es2019.string" />
/// <reference lib="es2019.symbol" />

Node.JS 가 지원하는 ES 버전에 맞는 맞는 lib 설정을 할 필요가 있을 것이다. 그렇다면 Node.JS가 어떤 버전의 ES를 지원하는지 잘 알아야 한다. 그런 곳을 정리해 놓은 곳이 있는데, 이것을 보고 lib에 ES 버전을 적절히 올리거나 필요한 것만 추가해서 사용하면 될 것 같다. 예를 들어, Node12 버전을 사용하는 경우, ES2019는 100% 지원하고 ES2020은 BigInt, Promose.allSettled 등을 일부 지원하므로 이런 것을 추가해서 사용하면 될 것 같다.

default는 ES3이고, 현대 JavaScript 브라우저와 애플리케이션은 보통은 ES6+에서 동작하므로 ES6(ES2015)로 설정하기를 개인적으로 권장한다. 만약 target을 설정했는데 lib를 생략했다면, lib는 target과 같은 버전으로 변경되어 동작하게 된다고 공식문서에서 설명하고 있다. 다음은 공식문서의 target 부분에서 인용한 것이다. 이 부분 때문이라도 lib를 target과 함께 봐두면 좋은 것 같다.

Changing target also changes the default value of lib. You may “mix and match” target and lib settings as desired, but you could just set target for convenience.

target

target은 TypeScript가 컴파일 되는 결과물인 JavaScript 코드로 변환되는 버전을 결정한다. 즉, 위의 lib 설정에서 밝힌 것 처럼, 만약 백엔드 Node.JS를 운영할 것이라면, 운영하는 Node.JS가 지원하는 버전의 ES 버전에 맞게 target을 지정하면 될 것이다. 프론트엔드라면 개발하려는 브라우져 버전에 맞게 target을 설정하면 될 것 같다.

allowJs

TypeScript는 기본적으로 JavaScript 위에서 동작하는 언어이고, JavaScript를 TypeScript로 점차적으로 변환시켜서 사용할 수도 있다. 이 점으로 볼 때, .ts 파일에서 .js 파일도 import 있게 할 수 있어야 하는 경우도 있을 것 같다. 그래서 allowJS는 .ts, .tsx 파일에서 .js 파일을 import 할 수 있게 해준다.

기본적으로 false 이지만, JavaScript 프로젝트를 점차 TypeScript로 변환시키는 경우 true로 설정하는 것이 필요할 것이다.

removeComments

TypeScript 코드를 JavaScript로 컴파일 시킬 때, 주석(comments)을 모두 제거 시키는 옵션이다.

기본적으로 false 이지만, 번들 사이드 등을 줄이기 위해 소스코드에서 주석을 제거하고 싶다면 true로 하면 된다.

sourceMap

sourcemap fiile(xxx.js.map)을 생성할 것인지 유무를 설정하는 것이다. 이 file은 JavaScript와 함께 생성되면, debugger나 다른 툴이 본래의 TypeScript 소드 코드를 볼 수 있게 해주도록 한다. hello.ts를 컴파일 하고 sourceMap을 true로 하면 hello.js와 함께 hello.js.map 파일이 생성되는 것을 볼 수 있을 것이다.

기본값은 false인데, 디버깅이 필요한 개발환경에서는 true로 하고, 배포 사이즈를 줄여야 하는 배포환경에서는 false 해, 서로 다른 환경에서 적절하게 컴파일 되도록 설정하면 될 것 같다.

Strict Checks

Type을 얼마나 엄격하게 검사할지를 검사하는 옵션이라고 보면 될 것 같다. strict 에는 8가지 옵션이 있다.

1) strict

2) alwaysStrict

3) noImplicityAny

4) noImplycityThis

5) strictBindCallApply

6) strictFunctionTypes

7) strictNullChecks

8) strictPropertyInitialization

위에서도 밝혔지만, 여기서는 각 옵션이 어떤 것인지를 간단히만 밝히고 있다. 더 자세한 설명은 공식문서를 보는 것이 더 잘 이해가 될 것이고 정확하다.

1) strict

만약 이 모든 옵션을 모두 사용하려면 단지, { "strict": true } 로 설정하면 될 것 같다. 하지만, JavaScript에서 TypeScript로 옮기는 경우에는 바로 strict 를 적용할 수 없으니 여러 옵션들 중 선택해서 사용해야 하는 경우도 있을 것이다. 그래서 나머지 strict 특징들을 알아두었다가 필요할 때 적절히 사용하는 것도 좋을 것 같다. 또한 나머지 각각의 특징을 이해하는 것이 strict를 이해하는 것이기도 할 것 같다. 그리고 strict: true로 설정한 후 TypsScript 버전을 올렸을 때 추가되는 속성이 있다면 그 시점에 타입에러가 발생할 수도 있을 것이다.