TypeScript 구성 옵션

이재철·2023년 3월 13일

tsc tsconfig typescript

TypeScript

목록 보기

1/11

tsc 옵션

자바스크립트에서 타입스크립트로 index.ts 파일을 컴파일 하기 위해 tsc index.ts 를 사용합니다.

tsc 명령은 타입스크립트의 대부분 옵션을 -- 플래그로 사용할 수 있습니다.
➡ index.js 파일 생성을 건더뛰고 타입검사만 실행 (--noEmit 플래그 전달)

tsc index.ts --noEmit

tsc 구성 옵션 목록은 tsc --all 으로 확인 할 수 있습니다.

pretty 모드

tsc CLI는 색상과 간격의 스타일을 지정해 가독성을 높히는 pretty 모드 를 지원합니다.
➡ 기본적으로 pretty 모드로 설정됩니다.

tsc index.ts --pretty false 을 사용하여 타입스크립트에 더 간결하고 색상이 없는 형식을 사용하도록 지시할 수 있습니다.

watch 모드

watch 모드( -w, --watch )를 사용하면 종료하는 대신 타입스크립트를 무기한 실행 상태로 유지하고, 모든 오류의 실시간 목록을 가져와 터미널을 지속 업데이트 합니다.
➡ 여러 파일에 걸쳐서 리팩터링 같은 대규모 변경 작업을 할 때 유용함

tsc index.ts -w

TSConfig 파일 설정하기

대부분의 구성 옵션을 디렉터리의 tsconfig.json (TSConfig) 파일에 구체적으로 명시할 수 있습니다.

tsconfig.json는 해당 디렉터리가 타입스크립트 프로젝트 루트임을 나타냅니다.
디렉터리에서 tsc 를 실행하면 해당 tsconfig.json 파일의 모든 구성 옵션을 읽습니다.

tsc 명령에 tsconfig.json 파일이 있는 디렉터리 경로 또는 tsc 가 tsconfig.json 대신 사용할 경로를 -p, --project 플래그에 전달하여 사용합니다.

tsc -p path/to/tsconfig.json

TSConfig 파일에서 사용 가능한 모든 구성옵션 목록은 tsconfig.json 참조하세요

tsconfig.json 생성하기

tsc 명령의 tsc --init 명령어를 사용합니다.
➡ 타입스크립트 프로젝트에서는 구성 파일을 생성하기 위해 해당 명령어를 사용하는 것을 권장합니다.

완전히 주석 처리된 tsconfig.json 파일이 생성됩니다.

{
	"compilerOptions": {
    	//...
    }
}

Compiler Options

CLI와 TSConfig 파일에서 사용 가능한 대부분의 옵션은 다음 두 가지 범주 중 하나로 분류됩니다.

컴파일러 : 포함된 각 파일이 타입스크립트에 따라 컴파일 되거나 타입을 확인하는 방법
파일 : 타입스크립트가 실행될 파일과 실행되지 않은 파일

파일 포함 옵션

기본적으로 현재 디렉터리와 하위 디렉터리에 있는 숨겨지지 않은 모든 .ts 파일에서 실행되며, 숨겨진 디렉터리와 node_modules 디렉터리는 무시합니다.
✅ 타입스크립트 구성은 실행할 파일 목록을 수정할 수 있습니다.

include

파일을 포함하는 가장 흔한 방법으로 tsconfig.json 의 최상위 include 속성을 사용합니다.
➡ src/ 디렉터리 안의 모든 타입스크립트 소스 파일을 재귀적으로 포함합니다.

{
	"include": ["src"]
}

포함할 파일을 더 세밀하게 제어하기 위해 include 문자열에 글로브(glob) 와일드 카드를 허용합니다.

*: 0 개이상의 문자와 일치합니다. (디렉터리 구분자 제외)
?: 하나의 문자와 일치합니다. (디렉터리 구분자 제외)
**/ : 모든 레벨에 중첩된 모든 디렉터리와 일치합니다.

{
	"include": [
    	"typings/**/*.d.ts",
      	"src/**/*??.*"
    ]
}

다음 구성 파일은 typings/ 하위의 중첩된 디렉터리의 .d.ts 파일과 화강자 앞의 파일명에 적어도 두 개 이상의 문자를 가진 src/ 하위 파일만 허용합니다.

✅ 대부분 프로젝트는 ["src"] 와 같은 간단한 include 컴파일러 옵션만으로 충분합니다.

exclude

프로젝트의 include 파일 목록에 타입스크립트로 컴파일할 수 없는 파일이 포함되는 경우가 있습니다.
➡ TSConfig 파일의 최상위 exclude 속성에 경로를 지정하고 include 에서 경로를 생략합니다.

{
  	"exclude" : ["**/external", "node_modules"], 
	"include" : ["src"]
}

exclude 는 include 의 시작 목록에서 파일을 제거하는 작업만 수행합니다.
✅ 타입스크립트는 비록 가져온 파일이 exclude 목록에 명시적으로 나열되어 있더라도 포함된 파일에 따라 가져온 모든 파일에서 실행됩니다.

대체 확장자

타입스크립트는 기본적으로 확장자가 .ts인 모든 파일을 읽을 수 있습니다.
그러나, 일부 프로젝트는 JSON 모듈 또는 리액트와 같은 JSX 구문 처럼 확장자가 다른 파일을 읽을 수 있어야 합니다.

JSX 구문

jsx

JSX 구문은 프리액트와 리액트 같은 UI 라이브러리에서 자주 사용합니다.
🟡 JSX 구문은 기술적으로 자바스크립트가 아닙니다.
🟢 자바스크립트로 컴파일 되는 자바스크립트 구문의 확장입니다.

JSX 구문을 사용하기 위해 두 가지를 수행합니다.

구성 옵션에서 jsx 컴파일러 옵션을 활성화
- preserve (.jsx)
- react (.js)
- react-native (.js)
.tsx 확장자로 파일 이름을 지정

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

.tsx 파일의 제네릭 화살표 함수

제네릭 화살표 함수의 구문이 JSX 구문과 충돌합니다.
➡ .tsx 파일에서 화살표 함수에 대한 타입 인수 <T> 를 작성하면 T 요소의 시작 태그에 대한 종료 태그가 없기 때문에 구문 오류가 발생합니다.

const handleChange = <T>(input: T) => input;

구문의 모호성을 해결하기 위해 = unknown 제약 조건을 추가할 수 있습니다.
➡ 타입 인수 기본 값이 unknown 타입이므로 코드 동작이 전혀 반영되지 않습니다.

const handleChange = <T = unknown>(input: T) => input;

resolveJsonModule

resolveJsonModule 컴파일러 옵션을 true 로 설정하면 .json 파일을 읽을 수 있습니다.
➡ .json 파일을 마치 객체를 내보내는 .ts 파일인 것처럼 가져오며 객체의 타입을 const 변수 인 것처럼 유추합니다.

	import { user } from "./user.json";
    console.log(user);

esModuleInterop 컴파일러 옵션을 사용하면 기본 가져오기를 사용할 수 있습니다.

	import data from "./actvist.json";

array 또는 number 같은 다른 리터널 타입을 포함한 JSON 파일이라면 import 구문으로 * 사용합니다.

	// user.json
	[
    	"SON",
      	"JON",
      	"LEE"
    ]

	// user.ts
	import * as users from "./actvist.json";
	console.log(users.length);

자바스크립트로 내보내기

바벨 같은 전용 컴파일러 도구 등장으로 타입스크립트 역할이 타입 검사만으로 축소되었지만, 여전히 타입스크립트에 의존하는 프로젝트도 많습니다.

outDir

기본적으로 타입스크립트 출력 파일은 해당 소스 파일과 동일한 위치에 생성합니다.

	users/
	 user.js
	 user.ts

🟢 경우에 따라 출력 파일을 다른 폴더에 생성하는 것이 더 나을 수 있습니다.
tsc --outDir dist 명령어를 실행하면 dist/ 폴더에 출력 파일을 생성합니다.

    dist/
      	users/
      		user.js
	users/
	 user.ts

✅ rootDir 컴파일러 옵션은 해당 루트 디렉터리를 명시적으로 지정하기 위해 존재하지만 . 또는 src 이외의 값을 사용할 일은 거의 없습니다.

target

타입스크립트는 자바스크립트 코드 구문을 지원하기 위해 어느 버전까지 변환해야 하는지를 지정하는 target 컴파일러 옵션을 제공합니다.
지정하지 않으면 이전 버전과 호환성을 위해 기본적으로 es3 이 지정됩니다.

tsc --init 은 기본으로 es2016 을 지정하도록 설정되어 있습니다.

🟡 오래된 환경에서 최신 자바스크립트 기능을 지원하려면 더 많은 자바스크립트 코드를 생성해야 하므로, 파일 크기가 조금 더 커지고 런타임 성능이 조금 저하 됩니다.

✅ target 컴파일러 옵션은 코드가 실행될 수 있는 가장 오래된 환경의 값으로 지정하면 코드가 구문 오류 없이 여전히 실행 가능한 현대적이로 간결한 구문으로 내보내집니다.

내보내기 선언

declaration 컴파일러 옵션을 사용해 소스 파일에서 .d.ts 출력 파일을 내보냅니다.

{
  	"compilerOptions" : {
		"declaration": true
    }
}

``.d.ts출력 파일은outDir옵션에 따라.js``` 파일과 동일한 출력 규칙에 따라 내보내집니다.

	users/
     user.d.ts
	 user.js
	 user.ts

emitDeclarationOnly

.js와 .jsx 파일 없이 선언 파일만 내보내도록 하는 emitDeclarationOnly 컴파일러 옵션이 존재합니다.
➡ 출력 선언 파일을 생성하려는 프로젝트에 유용합니다.

tsc --emitDeclarationOnly

{
  	"compilerOptions" : {
		"emitDeclarationOnly": true
    }
}

	users/
     user.d.ts
	 user.ts

소스 맵

소스 맵은 출력 파일의 내용이 원본 소스 파일과 어떻게 일치하는지에 대한 설명입니다.
➡ 브라우저 개발자 도구와 IDE에서 디버깅하는 동안 원본 소스 파일 내용을 볼 수 있도록 하는 시각적인 디버거에 특히 소스 맵이 유용합니다.

sourceMap

sourceMap 컴파일러 옵션을 사용하면 .js 또는 .jsx 출력 파일과 함께 .js.map 또는 .jsx.map 소스맵을 출력할 수 있습니다.

tsc --sourceMap

	users/
     user.js
	 user.js.map
	 user.ts

declarationMap

.d.ts 선언 파일에 대한 소스 맵을 생성할 수 있습니다.

tsc --declaration --declarationMap

	users/
     user.d.ts
	 user.d.ts.map
	 user.js
	 user.ts

noEmit

파일 생성을 모두 건너뛰도록 지정할 수 있습니다.
➡ 어떤한 파일도 생성되지 않습니다. 타입스크립트는 발견한 구문 또는 타입 오류만을 보고합니다.

타입검사

타입스크립트 구성 옵션은 타입 검사기를 제어합니다.

lib

lib 컴파일러 옵션은 브라우저 타입 포함을 나타내는 dom 과 target 컴파일러 옵션을 기본값으로 하는 문자열 배열을 사용합니다.
➡ lib 설정을 변경하는 이유는 브라우저에서 실행되지 않는 프로젝트에서 기본으로 포함된 dom을 제거하기 위함입니다.

✅ 최신 자바스크립트 API를 지원하기 위해 폴리필 을 사용하는 프로젝트에서 lib 컴파일러 옵션을 사용해 dom과 특정 ECMA스크립트 특정 버전을 포함할 수 있습니다.

{
  	"compilerOptions" : {
		"lib": ["dom", "es2020"]
    }
}

🔴 ES2020까지만 지원하는 플랫폼에서 실행되는 lib에서 String.replaceAll 과 같이 ES2021 이상에서 정의된 API를 사용하면 여전히 런타임 오류가 발생할 수 있습니다.

skipLibCheck

소스 코드에 명시적으로 포함되지 않은 선언 파일에서 타입 검사를 건너뛰도록 하는 skipLibCheck 컴파일러 옵션을 제공합니다.
➡ 공유된 라이브러리의 정의가 서로 다르고 충돌 할 수 있는 패키지 의존성을 많이 사용하는 애플리케이션에 유용합니다.

{
  	"compilerOptions" : {
		"skipLibCheck": true
    }
}

✅ 타입 검사 일부를 건너뛰는 작업으로 타입스크립트 성능을 개선합니다.
skipLibCheck 옵션을 활성화하는 것이 좋습니다.

엄격 모드

타입 검사 컴파일러 옵션은 대부분 strict mode 로 그룹화 됩니다.
defalut : false

엄격 옵션 중에 noImplicitAny 와 stringNullChecks 는 타입 안전 코드를 적용하는데 특히 유용합니다.

특정 검사를 제외한 모든 엄격 모드를 활성화하고 싶다면 strict 활성화
특정 검사를 명시적으로 비활성화 할 수있습니다.

{
  	"compilerOptions" : {
      	"noImplicitAny" : false,
		"strict": true
    }
}

noImplicitAny

매개변수 또는 속성의 타입을 유추할 수 없는 경우는 any 타입으로 가정합니다.
🔴 대부분 우회할 수 있으므로 코드에서 이러한 암시적 타입은 허용하지 않는 것이 좋습니다.

const logMessage = (message) => {
    // Error : Parameter 'message' implicitly has an 'any' type
	console.log('Message: ${message}!');
}

const logMessage = (message:string) => {
    // OK
	console.log('Message: ${message}!');
}

strictBindCallApply

내장된 Function.apply, Function.bind, Function.call 함수 유틸리티를 나타낼 수 있을 만큼 충분한 타입 시스템 기능이 없었습니다.
➡ any를 사용해야 했음, 안정성과는 매우 거리가 먼 상태

function getLength(text:string, trim?: boolean) {
	return trim ? text.trim().length : text;
}
// (thisArg : typeof getLength, args: [text:string, trim?: boolean]) => number
getLength.apply;
// (trim?: boolean) => number
getLength.bind(undefined, "abc123");
// number
getLength.call(undefined, "abc123", true);

✅ strictBindCallApply 옵션을 활성화하는 것이 좋습니다.
프로젝트의 타입 안정성을 개선하는 데 도움이 됩니다.

strictFunctionTypes

함수 매개변수 타입을 약간 더 엄격하게 검사합니다.
매개변수가 다른 타입의 매개변수 하위 타입인 경우 함수 타입은 더 이상 다른 함수 타입에 할당 가능한 것으로 간주되지 않습니다.

function checkOnNumber(containsA: (input: number | string) => boolean) {
	return containsA(1337);
}

function stringContainsA(input:string) {
	return !!input.match(/a/i);
}

checkOnNumber(stringContainsA);

checkOnNumber 함수는 number | string 을 받는 함수를 사용해야 하지만, 오직 타입이 string인 매개변수만 받을 것 으로 예상하는 stringContainsA 함수 제공

stringContainsA 함수가 제공되는 것을 허용하고, 프로그램은 매개 변수가 number인 경우 .match() 를 호출하려고 하면 문제가 발생합니다.

strictNullChecks

strictNullChecks 플래그를 비활성화하면 코드의 모든 타입에 null | undefined 가 추가되고,
➡ 모든 변수가 null 또는 undefined를 받을 수 있도록 허용합니다.

strictNullChecks 활성화 한경우, string 타입인 value에 null을 할당하면 타입 오류가 발생합니다.

let value : string;

value = "abc1234"; // OK
value = null; // ERROR

✅ strictNullChecks 옵션을 활성화하는 것이 좋습니다.
충돌을 방지할 수 있습니다.

strictPropertyInitialization

플래그는 초기화가 없고, 생성자에게 확실하게 할당되지 않은 클래스 속성에서 타입 오류를 발생합니다.

class Animal {
  private name: string; // error
  // 'name' is declared but its value is never
}

class Animal {
  private name: string;
  constructor(name: string) { // OK
    this.name = name;
  }
}

✅ strictPropertyInitialization 옵션을 활성화하는 것이 좋습니다.
클래스 초기화 로직 실수로 인한 충돌을 방지할 수 있습니다.

useUnknownInCatchVariables

catch 문에 error 변수의 타입을 변경할 수 있는 옵션
true : unknown
false : any

try {
	someExternalFunction()
} catch (error) {
	error; // 기본 타입 : any
}

any 사용과 마찬가지로 오류를 억지로 명시적 타입 어서션 또는 내로잉 하는 비용보다 unknown 으로 처리하는 것이 기술적으로 더 타당합니다.

try {
	someExternalFunction()
} catch (error : unknown) {
	error; // 기본 타입 : unknown
}

모듈

새로운 타입스크립트 프로젝트는 대부분 표준화된 ECMA스크립트 모듈 구문으로 작성됩니다.

import { value } from "my-example-value";

export const logValue = () => console.log(value);

module

어떤 모듈 시스템으로 변환된 코드를 사용할지 결정하기 위해 module 컴파일러 옵션을 제공합니다.
module 값에 따라 export와 import 문을 다른 모듈 시스템으로 변환할 수 있습니다.

{
  	"compilerOptions" : {
      	"module" : "commonjs"
    }
}

const my_example_lib = require("my-example-value");

export const logValue = () => console.log(my-example-value);

target 컴파일러 옵션이 es3 또는 es5 인 경우 module 컴파일러 옵션의 기본값은 commonjs 가 됩니다.

그렇지 않다면 ECMA스크립트 모듈로 출력하도록 지정하기 위해 module 컴파일러 옵션은 es2015 로 기본 설정됩니다.

moduleResolution

모듈 해석은 import에서 가져온 경로가 module에 매핑되는 과정입니다.

node : 기존 Node.js 와 같은 CommonJS 리졸버 에서 사용하는 동작
nodenext : ECMA스크립트 모듈에 대해 지정된 동작에 맞게 조정

🟡 두 전략은 유사하며, 차이를 느끼지 못합니다.

{
  	"compilerOptions" : {
      	"moduleResolution" : "nodenext"
    }
}

CommonJs와의 상호 운용성

자바스크립트 모듈로 작업할 때 모듈의 기본 내보내기와 네임스페이스 출력 간에는 차이점이 있습니다.

모듈의 기본 내보내기 : 내보낸 객체의 .default 속성
모듈의 네임스페이스 내보내기 : 내보낸 객체 자체

구분 영역	CommonJS	ECMA스크립트 모듈
기본 내보내기	module.exports.default = value;	export default value;
기본 가져오기	const { default: value } = require("...")	import value from "...";
네임스페이스 내보내기	module.exports = value	지원 안함
네임스페이스 가져오기	const value = require("...")	import * as value from "..."

🟡 대부분의 프로젝트 처럼 npm 패키지에 의존하는 경우 의존성 중 일부는 여전히 CommonJS 모듈로 배포됩니다.

esModuleInterop

module 이 es2015 또는 esnext 와 같은 ECMA스크립트 모듈 형식이 아닌 경우 타입스크립트에서 내보낸 자바스크립트 코드에 소량의 로직을 추가합니다.

✅ 기본 내보내기를 제공하지 않는 react 같은 패키지를 위해서입니다.

➡ esModuleInterop 은 내보낸 자바스크립트 코드가 가져오기로 작동하는 방식에 대해서만 직접 변경합니다.

allowSyntheticDefaultImports

ECMA스크립트 모듈이 호환되지 않는 CommonJS 네임스페이스 내보내기 파일에서 기본 가져오기를 할 수 있음을 타입 시스템에 알립니다.

allowSyntheticDefaultImports 컴파일러 옵션은 다음 중 하나가 true 인 경우에만 true 로 기본적 설정됩니다.

module이 system인 경우
esModuleInterop : true, module 이 es2015 또는 esnext 와 같은 ECMA스크립트 모듈 형식이 아닌 경우

➡ esModuleInterop : true 이지만 module : esnext 경우 타입스크립트는 컴파일된 출력 자바스크립트 코드가 가져오기 상호 운용성 지원을 사용하지 않는다고 가정합니다.

import React from "react"; 
// ERROR
// default-imported using the `allowSyntheticDefaultImports flag`

isolatedModules

한 번에 하나의 파일에서만 작동하는 바벨과 같은 외부 트랜스파일러는 타입 시스템 정보를 사용해 자바스크립트를 내보낼 수 없습니다.

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

✅ 프로젝트에서 타입스크립트가 아닌 다른 도구를 사용해 자바스크립트로 변환하는 경우 isolatedModules를 활성화 하는 것이 좋습니다.

자바스크립트

타입스크립트는 기본적으로 .js , .jsx 확장자를 가진 파일을 무시하지만 allowJs 와 checkJs 컴파일러 옵션을 사용하면 자바스크립트 파일을 읽고, 컴파일하고, 제한된 기능이지만 타입 검사도 할 수 있습니다.

allowJs

자바스크립트 파일에 선언된 구문을 타입스크립트 파일에서 타입 검사를 하도록 허용합니다. jsx 컴파일러 옵션과 결합하면 .jsx 파일도 검사할 수 있습니다.

import { value } from "./values";
console.log('Quote: '${value.toUpperCase()}'');

🟡 allowJs 가 활성화 되지않으면import 문은 알려진 타입을 갖지 못합니다.
기본적으로 암시적 any가 되거나 타입오류가 발생합니다.

allowJs 는 ECMA스크립트 target에 맞게 컴파일되고 자바스크립트로 내보내진 파일목록에 자바스크립트 파일을 추가합니다. 활성화 된 경우 소스 맵과 선언 파일도 생성됩니다.

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

✅ allowJs 가 활성화되면 가져온 value는 string 타입이 되며 오류도 발생하지 않습니다.

checkJs

자바스크립트 파일도 타입 검사가 가능합니다.

allowJs 옵션이 아직 true 가 아니라면 기본값을 true 로 설정하기
.js 와 .jsx 파일에서 타입 검사기 활성화 하기

{
  	"compilerOptions" : {
      	"checkJs" : true
    }
}

✅ checkJs 를 활성화하면 타입 스크립트가 자바스크립트 파일을 타입스크립트 관련 구문이 없는 타입스크립트 파일인 것 처럼 처리합니다.
타입 불일치, 철자가 틀린 변수명 등 타입스크립트 파일에서 일반적으로 발생하는 모든 오류를 발생시킬 수 있습니다.

// index.js
let myQuote = "Each person...";
console.log(quote); // Error

🔴 checkJs 가 활성화되지 않았다면 타입스크립트는 해당 버그에 대한 오류를 보고하지 않습니다.

@ts-check

파일 상단에 // @ts-check 주석을 사용해 파일별로 checkJs 를 활성화 합니다.

// index.js
// @ts-check
let myQuote = "Each person...";
console.log(quote); // Error

JSDoc 지원

allowJs 와 checkJs 가 활성화되면 타입스크립트는 코드의 모든 JSDoc 정의를 인식합니다.

// index.js

/**
/* @param {string} text
*/
function sentenceCase(text) {
	return '${text[0].toUpperCase()} ${text.slice(1)}.';
}

sentenceCase("hello world"); // Ok
sentenceCase(["hello", "world"]); // ERROR

구성 확장

TSConfig 파일이 다른 구성 파일에서 구성 값을 확장(extend) 하거나 복사하도록 선택하는 메커니즘을 제공합니다.

extends

extends 구성 옵션을 사용해 다른 TSConfig에서 확장할 수 있습니다.
extends는 다른 TSConfig 파일에 대한 경로를 가져오고 해당 파일의 모든 설정을 복사해야 함 을 나냅니다.

파생 또는 자식 구성에서 선언된 모든 옵션은 기본 또는 부모 구성에서 동일한 이름의 모든 옵션을 다시 정의합니다.

packages/* 디렉터리를 포함하는 모노레포(monorepo) 처럼 여러 개의 TSConfig가 있는 많은 저장소는 규칙에 따라 확장할 tsconfig.json 파일에 대한 tsconfig.base.json 파일을 생성합니다.

// tsconfig.base.json
{
  	"compilerOptions" : {
      	"strict" : true
    }
}

// packages/core/tsconfig.json
{
  	"extends": "../../tsconfig.base.json",
    "includes": ["src"]
}

compilerOptions 는 재귀적으로 고려됩니다.
파생된 TSConfig에서 특정 옵션을 재정의하지 않는 한 기본 TSConfig의 각 컴파일러 옵션은 파생된 TSConfig로 그대로 복사됩니다.

// packages/js/tsconfig.json
{
  	"extends": "../../tsconfig.base.json",
    "compilerOptions" : {
    	"allowJs" : true
    }
    "includes": ["src"]
}

확장 모듈

extends 속성은 다음 자바스크립트 가져오기 중 하나를 사용합니다.

절대 경로 : @ 또는 알파벳 문자로 시작
상대 경로 : 마침표(.)로 시작하는 로컬 파일 경로

extends 값이 절대 경로라면 npm 모듈에서 TSConfig를 확장함을 나타냅니다.
타입스크립트는 이름과 일치하는 패키지를 찾기 위해 일반 노드 모듈 확인 시스템을 사용합니다.

✅ 많은 조직에서 npm 패키지를 사용해 여러 저장소 또는 모노레포 내에서 타입스크립트 컴파일 옵션을 표준화 합니다.

// packages/tsconfig.json
{
  	"compilerOptions" : {
      	"strict" : true
    }
}

// packages/js/tsconfig.json
{
  	"extends": "@my-org/tsconfig",
    "compilerOptions" : {
      	"allowJs" : true
    }
    "includes": ["src"]
}

// packages/ts/tsconfig.json
{
  	"extends": "@my-org/tsconfig",
    "includes": ["src"]
}

구성 베이스

처음 부터 고유한 구성을 생성하거나 --init 제안을 하는 대신, 특정 런타임 환경에 맞게 미리 만들어진 베이스 TSConfig 파일로 시작할 수 있습니다.

디노에서 권장되는 TSConfig 베이스를 설치하려면 다음과 같이 진행합니다.

npm install --save-dev @tsconfig/deno
# or
yarn add --dev @tsconfig/deno

구성 패키지가 설치되고 나면 다른 npm 패키지 구성 확장처럼 참조할 수 있습니다.

// packages/js/tsconfig.json
{
  	"extends": "@tsconfig/deno/tsconfig.json",
}

프로젝트 레퍼런스

대규모 프로젝트에서 프로젝트의 서로 다른 영역에 서로 다른 구성 파일을 사용하는 것이 유용할 수 있습니다.
✅ 타입스크립트에서는 여러 개의 프로젝트를 함께 빌드하는 프로젝트 레퍼런스 시스템을 정의할 수 있습니다.

단일 TSConfig 파일을 사용하는 것보다 조금 더 작업이 많지만 몇 가지 핵심 이점이 있습니다.

특정 코드 영역에 대해 다른 컴파일러 옵션을 지정할 수 있습니다.
개별 프로젝트에 대한 빌드 출력을 캐시할 수 있으므로 종종 대규모 프로젝트의 빌드 시간이 훨씬 빨라집니다.
프로젝트 레퍼런스는 코드의 개별 영역을 구조화하는데 유용한 의존성 트리(특정 프로젝트가 다른 프로젝트에서 파일을 가져오는 것만 허용)를 실행합니다.

composite

composite 구성 옵션을 선택해 파일 시스템 입력과 출력이 제약 조건을 준수함을 나타냅니다.

composite : true 일 때는 다음과 같습니다.

rootDir 설정이 아직 명시적으로 설정되지 않았다면 기본적으로 TSConfig 파일이 포함된 디렉토리로 설정됩니다.
모든 구현 파일은 포함된 패턴과 일치하거나 파일 배열에 나열되어야 합니다.
declaration 컴파일 옵션은 반드시 true 여야 합ㄴ디ㅏ.

// core/tsconfig.json
{
    "compilerOptions" : {
    	"declaration" : true
    }
    "composite" : true
}

✅ 타입스크립트가 프로젝트에 대한 모든 입력 파일과 일치하는 .d.ts 파일을 생성하도록 강제할 때 유용합니다.
composite 옵션은 다음 refernces 구성 옵션과 함께 사용할 때 가장 유용합니다.

references

참조된 프로젝트에서 모듈을 가져오는 것은 출력 .d.ts 선언 파일에서 가져오는 것으로 타입 시스템에 표시됩니다.

다음 구성 스니펫은 core/ 디렉터리를 입력으로 참조하도록 shell/ 디렉터리를 설정합니다.

// shell/tsconfig.json
{
   "refernces" : [
     { "path" : "../core" }
   ]
}

💡 references 구성 옵션은 기본 TSConfig에서 extends를 통해 파생된 TSConfig로 복사되지 않습니다.

references 옵션은 다음 빌드 모드와 함께 사용할 때 가장 유용합니다.

빌드 모드

코드 영역이 프로젝트 레퍼런스를 사용하도록 한번 설정되면 빌드(build) 모드에서 -b 또는 --b CLI 플래그를 통해 tsc를 사용할 수 있습니다.

TSConfig의 참조된 프로젝트를 찾습니다.
최신 상태를 감지합니다.
오래된 프로젝트를 올바른 순서로 빌드합니다.
재공된 TSConfig 또는 TSConfig의 의존성이 변경된 경우 빌드합니다.

✅ 타입스크립트 빌드 모드 기능은 최신 프로젝트를 다시 빌드하는 것을 건너뛰도록 해 빌드 성능을 크게 향상시킵니다.

코디네이터 구성

저장소에서 타입스크립트 프로젝트 레퍼런스를 설정하는 편리한 방법은 빈 파일 배열과 저장소의 모든 프로젝트 레퍼런스에 대한 레퍼런스를 사용해 최상위 레벨의 tsconfig.josn을 설정하는 것입니다.

최상위 TSConfig는 타입스크립트가 파일 자체를 빌드하도록 지시하지 않습니다.
➡ 필요에 따라 참조된 프로젝트를 빌드하도록 타입스크립트에 알리려는 역할만 합니다.

다음은 tsconfig.json은 저장소의 packages/core 와 packages/shell 프로젝트를 빌드하는 것을 나타냅니다.

// tsconfig.json
{
   "files": [],
   "refernces" : [
     { "path" : "./packages/core" },
     { "path" : "./pacakages/shell" },
   ]
}

빌드 옵션 모드

빌드 모드는 몇 가지 빌드에 특화된 CLI 옵션을 지원합니다.

--clean : 지정된 프로젝트의 출력을 삭제합니다 (--dry 함께 사용할 수 있습니다.)
--dry : 수행할 작업을 보여주지만 실제로 아무것도 빌드하지 않습니다.
--force : 모든 프로젝트가 오래된 것처럼 작동합니다.
-w or --watch : 일반적인 타입스크립트 watch 모드와 유사합니다.

✅ 빌드 모드는 watch 모드를 지원하기 때문에 tsc b -w 같은 명령을 실행하면 대규모 프로젝트에서 모든 컴파일러 오류에 대한 최신 목록을 빠르게 확인 할 수 있습니다.

이재철

혼신의 힘을 다하다 🤷‍♂️

다음 포스트