tsconfig.json

김동현·2022년 2월 23일

tsconfig.json typescript

TypeScript

목록 보기

2/18

typescript 라이브러리

우리가 작성한 TypeScript 파일은 브라우저가 이해할 수 없기 때문에 이를 순수 JavaScript파일로 변환해주는 작업(컴파일)이 필요합니다.

컴파일을 위해서 타입스크립트 컴파일러인 typescript라는 외부 라이브러리를 설치해서 타입스크립트 컴파일 명령어를 실행할 수 있습니다.

npm install typescript -g

: typescript 라이브러리를 로컬 시스템 전역에 설치해줍니다.

tsc

tsc <filename>

: tsc 명령어를 사용하여 TypeScript 파일을 컴파일하면 컴파일된 JavaScript 파일이 결과물로 반환됩니다.

기본적으로 타입스크립트에서 발생한 에러를 컴파일 도중에 감지하더라고 컴파일을 차단하지 않고 단지 발생한 에러에 대해서 알려주고 자바스크립트 파일로 컴파일합니다.

watch mode

타입스크립트 파일이 변경된 경우 매번 tsc 명령어를 통해 컴파일을 해주어야 하는 것은 매우 번거로운 일입니다. 이를 해결하기 위해 "watch 모드"를 사용할 수 있습니다. watch 모드는 파일을 저장할 때 변경사항이 생긴 경우 자동적으로 컴파일을 해줍니다

tsc <filename> --watch 혹은 tsc <filename> -w

즉, --watch, -w 옵션을 통해 watch 모드에 들어갈 수 있고, 종료하기 위해서는 control + c를 입력해줍니다.

이는 특정 파일 하나에 대해서만 동작하기 때문에 다수의 파일인 경우 부적절합니다.

tsc --init

프로젝트에 tsconfig.json파일이 존재한다면 해당 경로가 프로젝트의 루트 경로가 됩니다. 이때 입력파일 없이 tsc 명령어만 입력한다면 루트 경로를 시작으로 모든 타입스크립트 파일을 컴파일하기 시작합니다.

watch 모드 또한 tsc --w나 tsc --watch를 입력하여 프로젝트 전체에 대해서 watch 모드를 적용할 수 있습니다.

tsconfig.json 파일을 생성하기 위해서 터미널에 tsc --init 명령어를 입력합니다. 입력시 기본 설정을 갖춘 tsconfig.json 파일이 생성됩니다. tsconfig.json 파일은 타입스크립트 컴파일러를 설정하는 파일입니다.

typescript 설정 파일

매번 tsc 명령어 매번 입력하는 것을 비효율적이므로 Webpack과 같은 모듈 번들러의 자동화 도구를 사용하는 것을 권장합니다,

그리고 tsc 명령어로 TypeScript 파일을 컴파일 할 때 부가적인 옵션을 설정할 수 있습니다. typescript의 설정 파일인 tsconfig.json 파일에 작성합니다. 즉, 타입스크립트 컴파일러의 동작을 설정할 수 있습니다.

옵션에 대한 자사한 내용은 여기에서 확인할 수 있습니다.

{
    "compilerOptions": {

        /* 기본 옵션 */
        "incremental": true, /* 증분 컴파일 설정 여부 */
        "target": "es5", /* 사용할 특정 ECMAScript 버전 설정: 'ES3' (기본), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', 혹은 'ESNEXT'. */
        "module": "commonjs", /* 모듈을 위한 코드 생성 설정: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */
        "lib": [], /* 컴파일에 포함될 라이브러리 파일 목록 */
        "allowJs": true, /* 자바스크립트 파일 컴파일 허용 여부 */
        "checkJs": true, /* .js 파일의 오류 검사 여부 */
        "jsx": "preserve", /* JSX 코드 생성 설정: 'preserve', 'react-native', 혹은 'react'. */
        "declaration": true, /* '.d.ts' 파일 생성 여부. */
        "declarationMap": true, /* 각 '.d.ts' 파일의 소스맵 생성 여부. */
        "sourceMap": true, /* '.map' 파일 생성 여부. */
        "outFile": "./", /* 단일 파일로 합쳐서 출력합니다. */
        "outDir": "./", /* 해당 디렉토리로 결과 구조를 보냅니다. */
        "rootDir": "./", /* 입력 파일의 루트 디렉토리(rootDir) 설정으로 --outDir로 결과 디렉토리 구조를 조작할 때 사용됩니다. */
        "composite": true, /* 프로젝트 컴파일 여부 */
        "tsBuildInfoFile": "./", /* 증분 컴파일 정보를 저장할 파일 */
        "removeComments": true, /* 주석 삭제 여부 */
        "noEmit": true, /* 결과 파일 내보낼지 여부 */
        "importHelpers": true, /* 'tslib'에서 헬퍼를 가져올 지 여부 */
        "downlevelIteration": true, /* 타겟이 'ES5', 'ES3'일 때에도 'for-of', spread 그리고 destructuring 문법 모두 지원 */
        "isolatedModules": true, /* 각 파일을 분리된 모듈로 트랜스파일 ('ts.transpileModule'과 비슷합니다). */
    
        /* 엄격한 타입-확인 옵션 */
        "strict": true, /* 모든 엄격한 타입-체킹 옵션 활성화 여부 */
        "noImplicitAny": true, /* 'any' 타입으로 구현된 표현식 혹은 정의 에러처리 여부 */
        "strictNullChecks": true, /* 엄격한 null 확인 여부 */
        "strictFunctionTypes": true, /* 함수 타입에 대한 엄격한 확인 여부 */
        "strictBindCallApply": true, /* 함수에 엄격한 'bind', 'call' 그리고 'apply' 메소드 사용 여부 */
        "strictPropertyInitialization": true, /* 클래스의 값 초기화에 엄격한 확인 여부 */
        "noImplicitThis": true, /* 'any' 타입으로 구현된 'this' 표현식 에러처리 여부 */
        "alwaysStrict": true, /* strict mode로 분석하고 모든 소스 파일에 "use strict"를 추가할 지 여부 */
        
        /* 추가적인 확인 */
        "noUnusedLocals": true, /* 사용되지 않은 지역 변수에 대한 에러보고 여부 */
        "noUnusedParameters": true, /* 사용되지 않은 파라미터에 대한 에러보고 여부 */
        "noImplicitReturns": true, /* 함수에서 코드의 모든 경로가 값을 반환하지 않을 시 에러보고 여부 */
        "noFallthroughCasesInSwitch": true, /* switch문에서 fallthrough 케이스에 대한 에러보고 여부 */

        /* 모듈 해석 옵션 */
        "moduleResolution": "node", /* 모듈 해석 방법 설정: 'node' (Node.js) 혹은 'classic' (TypeScript pre-1.6). */
        "baseUrl": "./", /* non-absolute한 모듈 이름을 처리할 기준 디렉토리 */
        "paths": {}, /* 'baseUrl'를 기준으로 불러올 모듈의 위치를 재지정하는 엔트리 시리즈 */
        "rootDirs": [], /* 결합된 컨텐츠가 런타임에서의 프로젝트 구조를 나타내는 루트 폴더들의 목록 */
        "typeRoots": [], /* 타입 정의를 포함할 폴더 목록, 설정 안 할 시 기본적으로 ./node_modules/@types로 설정 */
        "types": [], /* 컴파일중 포함될 타입 정의 파일 목록 */
        "allowSyntheticDefaultImports": true, /* default export이 아닌 모듈에서도 default import가 가능하게 할 지 여부, 해당 설정은 코드 추출에 영향은 주지 않고, 타입확인에만 영향을 줍니다. */
        "esModuleInterop": true, /* 모든 imports에 대한 namespace 생성을 통해 CommonJS와 ES Modules 간의 상호 운용성이 생기게할 지 여부, 'allowSyntheticDefaultImports'를 암시적으로 승인합니다. */
        "preserveSymlinks": true, /* symlik의 실제 경로를 처리하지 않을 지 여부 */
        "allowUmdGlobalAccess": true, /* UMD 전역을 모듈에서 접근할 수 있는 지 여부 */
        
        /* 소스 맵 옵션 */
        "sourceRoot": "", /* 소스 위치 대신 디버거가 알아야 할 TypeScript 파일이 위치할 곳 */
        "mapRoot": "", /* 생성된 위치 대신 디버거가 알아야 할 맵 파일이 위치할 곳 */
        "inlineSourceMap": true, /* 분리된 파일을 가지고 있는 대신, 단일 파일을 소스 맵과 가지고 있을 지 여부 */
        "inlineSources": true, /* 소스맵과 나란히 소스를 단일 파일로 내보낼 지 여부, '--inlineSourceMap' 혹은 '--sourceMap'가 설정되어 있어야 한다. */
        
        /* 실험적 옵션 */
        "experimentalDecorators": true, /* ES7의 decorators에 대한 실험적 지원 여부 */
        "emitDecoratorMetadata": true, /* decorator를 위한 타입 메타데이터를 내보내는 것에 대한 실험적 지원 여부 */

        /* 추가적 옵션 */
        "skipLibCheck": true, /* 정의 파일의 타입 확인을 건너 뛸 지 여부 */
        "forceConsistentCasingInFileNames": true /* 같은 파일에 대한 일관되지 않은 참조를 허용하지 않을 지 여부 */
    },
    exclude: ["컴파일 대상에서 제외할 대상"],
    include: ["컴파일할 대상"],
    files: ["컴파일할 특정 파일"]
}

출처: https://geonlee.tistory.com/214

`"compilerOptions"`

"compilerOptions"에는 타입스크립트 컴파일러의 설정 옵션을 설정합니다.

1. `"target"`

"target"은 어떤 자바스크립트 버전을 대상으로 코드를 트랜스파일링 것인지 타입스크립트 컴파일러에게 알려줍니다.

즉, 트랜스파일링될 특정 ECAMScript 버전을 설정합니다. 참고로 ESNext 값은 ES7이후 버전을 의미합니다.

"target" 옵션 값에 따라 "lib" 옵션값이 기본값으로 자동 정의 됩니다.

2. `"lib"`

"lib"에는 프로젝트에서 사용되는 자바스크립트 내장 라이브러리를 추가해줍니다. 즉, 트랜스파일링에 포함될 라이브러리를 배열의 요소로 작성해줍니다.

이때 라이브러리의 폴리필을 추가해주는 것이 아니라 단지 타입스크립트에게 해당 라이브러리를 사용한다고 알려주는 역할을 합니다.

3. `"jsx"`

.tsx 파일 확장자를 갖는 파일의 트랜스파일링 방식을 결정합니다.

"jsx": "preserve": .jsx 파일로 트랜스파일링되고, jsx 문법 그대로 유지됩니다.
"jsx": "react-native": .js 파일로 트랜스파일링되고, jsx 문법 그대로 유지됩니다.

4. `"allowJS"`

"allowJS"는 프로젝트에 자바스크립트 파일 import를 허용하도록 설정하는 옵셥입니다. true로 설정시 ts 파일 내 js 파일 import를 허용합니다.

5. `"checkJS"`

"checkJS"는 allowJs 옵션과 함께 사용되며 자바스크립트 파일에서 TypeScript의 타입 검사 기능을 사용하도록 설정하는 옵션입니다.

6. `"rootDir"`

프로젝트의 최상위 경로값을 작성해줍니다. 즉, 프로젝트 루트 디렉토리를 설정하는 옵션입니다.

명시하지 않은 경우 "./" 값으로 tsconfig.json 파일이 존재하는 디렉토리를 최상위 디렉토리로 인식합니다.

outDir 옵션의 값은 rootDir 값을 기준 경로로 갖게 됩니다. 즉, outDir 옵션은 rootDir 옵션에 영향을 받습니다.

7. `"outDir"`

"outDir"을 통해 컴파일되어 생성된 파일(.js)이 저장되는 위치를 설정하는 옵션입니다.

값으로 저장될 경로를 문자열로 작성해줍니다.

상대 경로 작성시 기준 경로는 rootDir 옵션에 작성된 경로를 기준 경로로 사용합니다.

9. `"outFile"`

"outFile"은 타입스크립트를 컴파일시 개별적으로 컴파일된 결과물을 생성하는 것이 아니라 모든 타입스크립트를 컴파일하여 "하나의 파일로 생성"하기 위해 사용합니다.

이때 값으로 경로 뿐만 아니라 생성될 번들 파일의 이름도 작성해주어야 합니다.

outFile 옵션은 module 옵션값이 "AMD" 또는 "System"일 경우에만 사용 가능

8. `"sourceMap"`

"sourceMap" 옵션은 .js.map 파일 생성 여부를 설정하는 옵션입니다.

소스맵 파일(.js.map) 파일은 트랜스파일된 파일(.js)과 매핑되어 ts 파일 디버깅을 하는데 사용됩니다.

10. `"removeComments"`

"removeComments"는 모든 컴파일된 자바스크립트 파일에서 주석이 제거됩니다. 이는 컴파일된 자바스크립트 파일의 크기를 줄이는데 유용하게 사용됩니다.

11. `"noEmit"`

"noEmit"은 컴파일된 결과물인 자바스크립트 파일을 생성하지 않도록 합니다. 이는 컴파일시 자바스크립트 파일을 생성하지 않으면서 타입스크립트 컴파일러가 파일을 검사하고 에러를 보고하는 기능만을 위해 사용합니다.

12. `"noEmitOnError"`

"noEmitOnError"는 기본값이 false 입니다.

false는 컴파일시 에러가 존재하더라도 자바스크립트 파일을 생성하게 됩니다.

true를 작성하게 되면 타입스크립트 파일 내 에러가 존재한다면 자바스크립트 파일을 생성하지 않습니다. 이때 하나의 타입스크립트 파일이라도 에러가 존재한다면 나머지 파일들도 자바스크립트 파일을 생성하지 않습니다.

13. `"downlevelIteration"`

"downlevelIteration"은 target이 ES6 이전이라도 for..of 문이나 스프레드 문법, 디스트럭처링 문법을 지원하도록 하는 설정입니다.

14. `"module"`

"module" 옵션은 사용할 모듈 시스템을 설정하는 옵션입니다. 즉, 트랜스파일링된 파일에서의 모듈 시스템을 설정합니다.

module 옵션은 target 옵션값에 따라 기본값이 자동 정의됩니다.

target 옵션값이 ES6 미만인 경우 module 옵션값은 commonjs로 설정됩니다(require, export).
target 옵션값이 ES6 이상인 경우 module 옵션값은 ES6로 설정됩니다(import, export).

15. `"moduleResolution"`

"moduleResolution"는 모듈 경로의 해석 방식을 설정하는 옵션입니다.

node 값은 비 상대경로 모듈을 불러올 때 node_modules 디렉토리를 시작으로 하위로 내려가면서 탐색합니다.
classic 값은 비 상대경로 모듈을 불러올 때 해당 파일이 존재하는 디렉토리부터 상위로 올라가면서 탐색을 시작합니다.

moduleResolution 옵션값은 module 옵션값에 따라 기본값이 자동 정의 됩니다.

module 옵션값이 commonjs와 같이 Node.js인 경우 moduleResolution 값은 node로 설정됩니다.
module 옵션값이 amd, ES6, ESNext와 같이 웹인 경우 moduleResolution 값은 classic으로 설정됩니다.

16. `"baseUrl"`

import 구문의 상대경로와 절대경로의 기준 경로를 설정하는 옵션입니다.

비 상대경로의 경우에는 moduleResolution 옵션에 의해 결정됩니다.

17. `"paths"`

baseUrl 옵션에 작성된 기준 경로를 사용하여 특정 경로에 대한 별칭을 생성하는 옵션입니다.

,,,
"baseUrl": "./",
"paths": [
    "componentDir": "src/components/*"
],

다음과 같이 설정했을 때 componentDir/를 경로로 사용시 실제 경로는 ./src/components/로 사용됩니다.

@types 라이브러리와 겹치지지 않도록 경로 별칭 선두에 @ 사용을 주의해야 합니다.

18. typeRoots

기본적으로 npm으로 설치한 @types 패키지들은 node_modules 폴더에 있더라도 트랜스파일링 대상으로 추가가 됩니다.

즉, 기본값은 ["./node_modules/@types" ]입니다.

당연히 include에 포함된 타입 파일들(.d.ts)도 자동적으로 트랜스파일 대상으로 포함됩니다.

그러므로 typeRoots 옵션에는 include에 작성된 경로 외부에 있는 타입 파일(.d.ts)이 존재하는 경로를 작성해주어 트랜스파일 대상으로 포함시키는 옵션입니다.

만약 typeRoots 옵션을 명시하는 경우 "node_modules/@types"도 명시적으로 작성해주어야 합니다.

19. esModuleInterop

commongjs 방식의 모듈을 import 방식으로 가져올 수 없기 때문에 esModuleInterop 옵션값을 true로 설정하여 commonjs 모듈도 import로 가져올 수 있도록 합니다.

20. isolatedModules

타입스크립트 파일 내 import / export 문이 없는 경우 해당 파일은 전역 공간으로 정의됩니다. isolatedModules 옵션값 true로 설정하는 경우 모든 파일에 import / export 문 작성을 강제하여 모든 파일을 외부 모듈 파일로 인식되도록 합니다.

21. `"strcit"`

"strcit"옵션을 true로 설정시 Strict Type-Checking Options 옵션들("noImplicitAny", "strcitNullChecks", "strcitFunctionTypes", "strcitBindCallApply", "strcitPropertyInitialization", "noImplicitThis", "alwaysStrcit")을 모두 true로 설정하는 역할을 합니다.

22. `"noImplicitAny"`

"noImplicitAny"을 true로 설정시 any 타입으로 타입 추론되는 것을 허용하지 않습니다.

23. `"strictNullChecks"`

"strictNullChecks"을 true로 설정시 null과 undefined 타입은 다른 타입의 서브 타입으로 사용할 수 없도록 합니다.

또한 null이나 undefined에 대한 접근을 허용하지 않도록합니다.

24. `"strictBindCallApply"`

"strictBindCallApply"를 true로 설정시 Function#bind, apply, call 메서드 사용시 엄격하게 검사해줍니다. 이는 전달되어야 하는 인수가 제대로 전달되었는지와 같은 검사를 엄격하게 합니다.

25. `"noImplicitThis"`

"noImplicitThis"를 true로 설정시 any 타입으로 구현된 this를 에러 표시해줍니다.

26. `"alwaysStrict"`

"alwaysStrict"를 true로 설정시 자바스크립트 파일을 strict mode로 분석하고, 컴파일된 자바스크립트 파일에 "use strict";를 추가해줍니다.

27. `"noUnusedLocals"`

"noUnusedLocals"를 true로 설정시 선언은 되었지만 사용되지 않는 지역 변수에 대해서 에러를 표시합니다.

전역 변수의 경우에는 다른 스크립트에서 사용할 수도 있기 때문에 에러를 표시하지 않습니다.

28. `"noUnusedParameters"`

"noUnusedParameters"를 true로 설정시 사용되지 않는 매개변수에 대해서 에러를 표시해줍니다.

29. `"noImplicitReturns"`

"noImplicitReturns"를 true로 설정시 함수 몸체 실행시 일부 반환값이 없는 경우 에러를 발생시킵니다.

이는 함수 실행에 있어서 어떤 분기에서도 아무것도 반환하지 않는 경우에는 반환값이 없어도 에러를 발생시키지 않지만, 반환하는 분기가 하나라도 있다면 모든 분기의 경우에 반환하도록 작성해주어야 합니다.

`"files"`

"files" 옵션은 트랜스파일될 특정 파일을 명시하는 옵션입니다. 컴파일 할 특정 파일을 문자열 요소로 갖는 배열을 작성하면 tsc 명령어 실행시 지정된 파일들만 컴파일 됩니다.

파일명을 작성할 때 파일 확장자도 명시해주어야 합니다.

`"include"`

"include" 옵션은 트랜스파일될 파일명이나 경로를 작성하는 옵션입니다.

값으로 컴파일할 특정 파일명이나 패턴(glob 패턴)을 문자열 요소로 갖는 배열을 작성합니다.

이때 파일 확장자를 작성하지 않아도 자동적으로 .ts, .tsx, .d.ts 파일만을 대상으로 트랜스파일 됩니다.
allowJs 옵션값이 true라면 .js, .jsx 확장자도 포함됩니다.

glob 패턴

"/**": 하위 경로
"*": 0 이상의 모든 문자
"?": 1개 문자

예를 들어, "src/**/*"는 src 폴더의 하위 경로에 존재하는 모든 파일들을 의미하고, "**/*.d.ts"는 프로젝트 내 확장자가 .d.ts인 모든 파일들을 의미합니다.

`"exclude"`

"exclude"에는 트랜스파일에 제외할 파일이나 경로를 문자열 요소로 갖는 배열을 작성해줍니다.

이때 include에 작성된 대상중 제외할 대상을 설정하는 옵션입니다. 즉, files 옵션에 작성된 대상은 제외되지 않고 include에 작성된 대상만을 제외시키는 옵션입니다.

exclude 옵션을 명시하지 않는 경우에는 자동적으로 [ "node_modules", "bower_components", "jspm_packages" ]가 exclude 기본값으로 정의됩니다.

김동현

Frontend Dev

이전 포스트

tsconfig.json

TypeScript

typescript 라이브러리

tsc

watch mode

tsc --init

typescript 설정 파일

"compilerOptions"

1. "target"

2. "lib"

3. "jsx"

4. "allowJS"

5. "checkJS"

6. "rootDir"

7. "outDir"

9. "outFile"

8. "sourceMap"

10. "removeComments"

11. "noEmit"

12. "noEmitOnError"

13. "downlevelIteration"

14. "module"

15. "moduleResolution"

16. "baseUrl"

17. "paths"