[TS] tsconfig.json

Jane·2023년 8월 15일

typescript

TypeScript

목록 보기

13/17

1. tsconfig의 역할은 무엇인가?

🤔 tsconfig.json이란?

프로젝트를 컴파일하는데 필요한 루트 파일과 컴파일러 옵션을 지정해주는 파일
디렉토리에 tsconfig.json 파일이 있으면 해당 디렉토리가 TS 프로젝트의 루트가 된다.
jsconfig.json과 거의 동일하게 동작하나 jsconfig.json에는 JS 관련 컴파일러 플래그가 기본으로 활성화되어 있다.

디렉토리

컴퓨팅에서 파일을 분류하기 위해 사용하는 이름 공간
파일 시스템의 관점에서 파일들을 묶어두는 것
폴더와 유사한 개념이나 폴더는 파일 시스템에는 존재하지 않는 특수 항목들까지 아우를 수 있다.

🤖 tsconfig.json의 역할

🌟 1. tsc가 TS를 컴파일하는 방법을 제어한다.

tsc 커맨드 라인에 입력 파일 지정 시
- tsconfig.json 파일이 무시된다.
- tsc 커맨드의 인자로 TS 파일명을 넘기면 해당 파일에 저장된 소스 코드가 JS로 변환됨
- 컴파일의 결과물로 동일 디렉토리에 파일명은 동일하고 확장자가 .js인 파일이 생성됨
입력 파일 없이 tsc 호출 시
- TS를 JS로 컴파일하는 과정에서 tsconfig.json을 사용한다.
- 컴파일러는 현재 디렉토리에서부터 시작하여 상위 디렉토리 체인으로 tsconfig.json 파일을 검색한다.

🧐 tsc는 tsconfig.json 없이도 쓸 수 있는 것 아닌가?

사용 가능하다.
하지만 매번 번거롭게 명령어에 옵션을 주지 않아도 되고, 프로젝트의 설정을 일정하게 유지시키기 위해 tsconfig.json을 사용한다.

🌟 2. VS Code의 intellisense가 TS를 처리하는 방법을 제어한다.

VS Code는 기본적으로 TS에 대한 intellisense를 제공한다.
이 intellisense가 .ts 파일을 인식하는 방법을 제어하기 위해 tsconfig.json 파일을 사용한다.
VS Code는 TS 프로젝트 디렉토리의 root에 tsconfig.json을 넣고, 별도로 위치를 설정하는 방법을 제공하지 않는다.

(tsc의 경우 --build로 지정 가능!)
tsc가 컴파일 과정에서 tsconfig.json을 사용하는 것과는 아예 별개의 과정!

⚒️ intellisense

코딩을 보다 편리하게 하는 기능 집합에 지정된 이름
코드 문법 자동 완성 기능

2. tsconfig는 어디까지의 역할을 할 수 있을까?

🔅 컴파일러 옵션 설정

tsconfig.json의 compilerOptions를 사용해 코드 변환 과정에서의 동작 방식을 설정해줄 수 있다.
컴파일할 ECMA Script의 버전을 선택하거나, 모듈 시스템을 설정하고, 컴파일된 결과물과 컴파일할 코드 파일의 디렉토리 경로를 지정해주는 등 다양한 설정이 가능하다.

🔅 파일 포함 및 제외 설정

files, include, exclude를 사용해 컴파일할 파일과 제외할 파일을 명시적으로 지정해줄 수 있다.

🔅 타입 검사 및 엄격한 검사 설정

코드에서 발생할 수 있는 잠재적 오류 방지를 위해 엄격한 검사 옵션을 실행할 수 있다.
TS에서 기본적으로 제공하는 타입 검사 옵션인 strict 를 사용하면 타입이 지정되지 않은 변수나 함수의 사용이 불가능해지는 등 타입 안정성을 강화하고 JS 코드의 오류를 방지할 수 있다.

🔅 모듈 별칭 및 패스 매핑 설정

tsconfig.json을 통해 모듈 별칭을 설정함으로써 모듈의 경로를 단축할 수 있다.
디렉토리 구조가 복잡한 프로젝트에서 baseUrl과 paths를 사용하면 상대 경로를 절대 경로로 설정하여 모듈을 찾는데 드는 시간을 단축시킬 수 있다.

🔅 소스 맵 생성 및 디버깅 설정

sourceMap 옵션을 통해 소스맵을 활성화하여 브라우저에서 JS 런타임 오류 발생 시 디버깅하는 과정에서 유용하게 사용할 수 있다.
TS의 디버깅 설정 옵션(inlineSources, mapRoot, outDir, sourceRoot 등)을 통해 디버깅에 필요한 정보를 제공 받고, 디버깅 과정에서 발생할 수 있는 문제를 방지할 수 있다.
디버깅 시 소스 코드와 컴파일된 코드의 관계를 더욱 명확하게 파악할 수 있게 되며, 소스맵을 통해 컴파일된 코드에서 소스 코드로 쉽게 이동할 수 있다.

소스맵

TS 코드와 컴파일된 JS 코드 간의 매핑 정보를 담고 있는 파일
디버깅 시 컴파일 된 JS 코드에서 원본 TS 코드의 위치를 찾을 수 있도록 도와준다.

🔅 추가 설정 파일 참조

extends 항목을 사용하여 다른 tsconfig.json의 파일을 참조할 수 있다.
이를 통해 여러 가지 설정 파일을 나누어 작성하고 필요한 설정 파일만으로 프로젝트 구상이 가능하다.

// tsconfig.json
{
  "extends": "./base-tsconfig.json",
  "compilerOptions": {
    ...
  },
  "include": ...
}

위의 코드 예시처럼 compilerOptions는 tsconfig.json에서 작성하고, 나머지 설정을 extends를 통해 다른 파일에서 상속받아 사용할 수 있다.
여러 설정 파일이 있을 경우 이처럼 상속 구조를 만들어 최종 설정 파일에서 필요한 옵션만 지정해 사용할 수 있다.

3. tsconfig의 주요 옵션

⚙️ 최상위 속성

files

컴파일러를 통해 프로그램에 포함하고 싶은 파일들의 목록을 지정한다.
파일 확장자까지 정확히 명시해줘야 한다.
파일의 URL은 상대/절대 경로 모두 될 수 있다.
배열의 요소 중 하나라도 존재하지 않으면 에러 발생!

{
  "**files**": [
    "core.ts",
    "sys.ts",
    "types.ts",
    ...
  ]
}

파일을 몇 개 가지고 있지 않아 glob 패턴이 필요없는 작은 프로젝트인 경우 유용하다.

🔎 glob 패턴
  - 특정 경로, 특정 이름을 가진 파일들을 선택하기 위해 사용하는 옵션
  - 여러 와일드카드 문자를 사용하여 다수의 파일 집합을 지정하는 방식

include

프로그램에 포함하고 싶은 파일들의 목록을 지정한다.
include를 지정하더라도 files 속성에 지정한 파일들은 제외되지 않는다.

"**include**": [
        "src/**/*"
    ],

files 속성처럼 상대 경로를 직접 지정할 수도 있지만, include와 exclude 속성은 glob 패턴을 지원하므로 많은 파일을 한 번에 가리키도록 지정하는 것이 가능하다.
include와 exclude 속성의 glob 패턴
- * : 0개 이상(없거나 하나 이상)의 문자들과 매칭된다. (디렉토리 구분자 제외)
- ? : 한 문자와 매칭된다. (디렉토리 구분자 제외)
- **/ : 단계에 관계 없이 반복적으로 모든 하위 디렉토리와 매칭된다.
glob 패턴이 파일 확장자를 포함하지 않는 경우 지원되는 파일 확장자들만 포함된다.
- 기본적으로 .ts, .tsx, .d.ts확장자 지원
- allowJS 속성이 true라면 .js, .jsx 확장자까지 지원

exclude

include 속성에 의해 프로그램에 포함되는 파일들 중 제외시킨 파일들의 목록을 지정한다.
특정 파일이 프로그램에 아예 포함되지 못하게 막는 것은 아니고, include 속성으로 지정한 파일의 목록에만 영향을 미친다.
- exclude로 지정하였더라도 files, import, ///reference 등을 통해 프로그램에 추가될 수 있다.
- files 속성에서 명시된 파일은 exclude에 관계 없이 항상 포함된다.

 "**exclude**": [
        "node_modules",
        "**/*.spec.ts"
    ]

지정하지 않을 경우 ["node_modules", "bower_components", "jspm_packages"] + outDir에 지정한 경로가 기본값이 된다.

compileOnSave

IDE에 최상위 속성으로 설정 시 저장할 때 지정된 tsconfig.json에 대한 모든 파일을 생성한다.

{
  "compileOnSave": true
}

⚙️ compilerOptions 속성

선택된 파일들을 처리하는 설정
생략될 수 있으며 생략 시 컴파일러의 기본 값이 사용된다.

기본 옵션

noEmit (boolean)

컴파일러가 JS 파일 등의 출력 파일을 만들어내지 않도록 하는 설정
true일 경우 Babel 등의 도구가 TS 파일을 JS 파일로 변환하는 작업을 담당할 수 있게 한다.
- 이때 TypeScript는 에디터 통합 기능 제공 도구 또는 소스 코드 타입 체커로만 사용된다.

target (string)

어떤 버전의 JS 코드로 컴파일 할지 결정한다.
tsc가 최종적으로 컴파일하는 결과물의 문법 형태를 결정한다.

ECMAScript 대상 버전 지정
- "ES3" (기본 값)
- "ES5"
- "ES6"/"ES2015"
...
- "ESNext": 현재 사용하고 있는 버전의 TS가 지원하는 가장 높은 버전

만약 ES5나 그 이전 버전으로 지정되면 컴파일 시 코드에 작성한 화살표 함수는 모두 function 표현법으로 변환된다.
target에 따라 사용할 수 있는 기능이 제한될 수 있다.

lib (string[])

현재 프로젝트에서 사용할 수 있는 특정 기능에 대한 문법(타입)을 추가해주는 설정
컴파일에 포함될 라이브러리 파일 목록
설정하는 target에 따라 기본적으로 다르게 설정된다.
지정하지 않을 경우 target에 따른 기본 리스트가 삽입된다.
사용 예시
```
"compilerOptions" : [
  "lib" : ["DOM"]
]
```
- TS는 기본적으로 DOM 관련 API를 문법에 추가하지 않는다.
- 이때 "DOM"을 lib에 지정해줌으로써 DOM 관련 API (document.querySelector) 등을 사용할 수 있게 된다.
하지만 런타임에 해당 기능들을 추가해주지는 않는다.
- target은 ES5인데 lib을 ES6로 설정하고 ES6의 기능을 사용하면 에러가 발생하지 않고 컴파일도 정상적으로 진행되나 런타임이 ES5만 지원할 경우 런타임 에러가 발생한다.
polyfill(하위 브라우저가 지원하는 JS 코드를 사용해 JS의 최신 기능을 똑같이 구현하는 방식)은 알아서 해야 한다.

module (string)

프로그램에서 사용할 모듈 시스템을 결정한다.
모듈 내보내기/불러옥 코드가 어떤 방식의 코드로 컴파일 될지 결정한다.
Node.js 프로젝트의 경우 보통 CommonJS를 선택한다.

jsx (string)

.tsx 파일 컴파일 시 JSX 코드를 어떻게 컴파일 할지 결정한다.

// preserve
export const Main = () => <div>:)<div>;

// react
export const Main = () => React.createElement("div", null, ":)");

allowJS (boolean)

TS 프로젝트에서 JS 파일도 사용할 수 있게 하는 설정
true이면 JS 파일도 프로젝트에서 import 될 수 있다.
JS 프로젝트를 TS 프로젝트로 마이그레이션 시 TS 문법으로 점진적으로 전환하려 할 때 유용하다.

outDir (string)

files와 include를 통해 선택된 파일들의 결과문이 출력되는 디렉토리를 설정할 수 있다.

isolatedModules (boolean)

각 파일을 별도의 모듈로 변환한다.
추가 검사를 수행하여 별도의 컴파일이 안전한지 확인한다.
true로 설정 시 프로젝트 내 모든 소스코드 파일을 강제로 각각의 모듈로 만든다.
babel과 같은 외부 도구 사용 시 true로 설정해주는 것이 좋다.

declaration (boolean)

해당하는 .d.ts 파일을 생성한다.
true로 설정 시 .ts v파일의 .d.ts 파일 또한 같이 출력물에 포함된다.

sourceMap (boolean)

해당하는 소스맵 .map 파일을 생성한다.
true로 지정 시 출력 결과에 .js.map이나 .jsx.map 파일을 포함시킨다.

엄격한 유형 검사 옵션

stirct (boolean)

모든 엄격한 타입 검사 옵션을 활성화한다.

이를 통해 활성화되는 옵션들의 예시

옵션명	타입	설명
noImplicitAny	boolean	any 타입으로 암시한 표현식과 선언에 오류 발생
alwaysStrict	boolean	strict mode에서 파싱 후 각 소스 파일에 `use strict` 반환
strictNullChecks	boolean	`true`이면 null과 undefined 타입에는 그 자체와 any만 할당 가능
strictFunctionTypes	boolean	엄격한 함수 유형 검사 사용

추가 검사 옵션

noFallthroughCasesInSwitch (boolean)

switch 문의 fallthrough 케이스에 대한 오류를 보고한다.
- fallthrough 케이스: switch 문에서 case 내에서 의도적으로 break문을 생략하여 다음 case로 이동 시키는 방법
switch문에서 비어있지 않은 케이스의 경우 반드시 break나 return문으로 해당 케이스를 종료시키도록 강제한다.

모듈 분석 옵션

moduleResolution (string)

모듈 해석 방법을 결정한다.
Node.js 해석의 경우 node (Node.js)를 사용한다.
node로 설정한다고 해서 Node.js의 node_modules의 모듈을 가져오는 것은 아니고, Node.js의 방식으로 모듈을 찾는다는 것을 의미한다.

baseUrl (string)

절대경로 모듈 이름을 해석하기 위한 기본 디렉터리
외부 모듈이 아닌 이상 상대 경로로 모듈을 참조해야 하는데, baseUrl을 통해 외부 모듈이 아닌 모듈도 절대 경로로 참조할 수 있다.
다만 외부 번들러 (예: webpack) 사용 시 별도의 설정이 필요하다.

paths (Object)

baseUrl을 기준으로 관련된 위치에 모듈이름의 경로 매핑 목록을 나열한다.
baseUrl 지정을 통해 모듈 참조된 절대 경로를 더 상세하게 설정할 수 있게 한다.
baseUrl과 마찬가지로 외부 번들러 (예: webpack) 사용 시 별도의 설정이 필요하다.

typeRoots (string[])

타입 정의가 포함될 폴더의 목록
기본값: ["node_modules/@types"]
tsconfig.json이 있는 곳으로부터 상대 경로로 작성한다.
추가적으로 타입 정의 시 별도의 type 디렉토리 생성 후 그 안에 .d.ts를 만들고 해당 디렉터리를 typeRoots에 추가하면 된다.
다만, include에 포함되어 있는 .d.ts 파일은 자동으로 TS가 인식하므로 넣어주지 않아도 된다.
주로 외부 라이브러리 모듈의 타입을 정의하기 위해 사용한다.

types (string[])

타입 정의가 포함될 이름의 목록
컴파일 시 포함될 유형 선언 파일을 입력한다.

🌟 typeRoots VS. types
    - typeRoots 속성은 컴파일 목록에 자동으로 포함시킬 패키지들의 경로를 지정한다.
    - types 속성 지정 시 typesRoots 속성에 지정된 경로에서 types 속성으로 지정된 패키지들만 컴파일 목록에 포함되고 나머지는 포함되지 않는다.

    - typeRoots: 컴파일 목록에 자동으로 포함시킬 패키지들의 기준 디렉토리
    - types: 그 디렉토리 내에 존재하는 패키지들 중 어떤 패키지들을 컴파일 목록에 포함시킬지 결정

    - types 속성이 지정되어 있지 않다면 typesRoots 속성에 지정된 경로의 패키지들은 모두 컴파일 목록에 자동 포함된다.

allowSyntheticDefaultImports (boolean)

default export가 없는 모듈에서 default imports를 허용한다.
코드 방출에는 영향을 미치지 않고, 타입 검사만 수행한다.

esModuleInterop (boolean)

모든 가져오기에 대한 네임스페이스 객체 생성을 통해 CommonJS와 ES 모듈 간 상호 운용성을 제공한다.
ES6가 아닌 CommonJS의 경우 모듈의 export 방식이 다르다.
- ES6: export 시 이름을 지정하고 default로 내보낸다.
- ES6가 아닌 CommonJS: module.exports = ...를 통해 객체를 내보낸다.
- 이 때문에 ES6가 아닌 CommonJS로 작성된 객체는 default import를 할 수 없어 import * as ... from "..." 방식으로 import 해야 한다.
이때 esModuleInterop을 true로 설정해주면 TS가 두 방식의 차이를 자동으로 해소해준다.

고급 옵션

skipLibCheck (boolean)

모든 선언 파일의 .d.ts 타입 검사를 건너뛴다.
이를 통해 외부 라이브러리 모듈 참조 시 프로젝트 내부에는 문제가 없음에도 불구하고 외부 라이브러리의 타입 정의가 잘못돼 있어 오류가 나는 경우를 막을 수 있다.

🤔 내부 프로젝트의 .d.ts 파일까지 검사가 생략되진 않을까?
    : .d.ts 파일은 외부용으로 사용되는 것이 일반적이므로,
    내부 프로젝트에서 .d.ts 파일 정의를 하지 않으면 내부 프로젝트의 검사가 생략되는 문제가 발생하지 않는다.
    타입 정의를 .ts 파일에서 하고 export, import하여 사용하자!

forceConsistentCasingInFileNames (boolean)

사용할 파일의 이름을 대소문자까지 정확하게 작성하도록 강제하는 설정
동일 파일 참조에 대해 일관성 없는 케이스 참조를 비활성화한다.

4. tsconfig 활용하기

🚩 tsConfig를 활용해 상대 경로를 절대 경로로 만들기

// tsconfig.json
{
  "compilerOptions": {
    // 1. 기본 경로: 프로젝트 최상단으로 설정
     "baseUrl": ".",
    // 2. src 이하를 절대 경로로 지정하고자 하는 경로로 지정해주기
    "paths": {
      "@/*": ["src/*"]
    },

}