Typescript 컴파일러 옵션

🔍 타입스크립트 컴파일러 옵션

타입스크립트의 컴파일과정에서는 작성한 코드에 타입 오류가 없는지 검사하고 오류가 없다면 자바스크립트 코드로 변환합니다.

이 컴파일 과정의 세부적인 사항들을 컴파일 옵션이라고 하고 개발자가 직접 설정하여 각자 원하는 방향으로 컴파일 옵션을 설정할 수 있습니다.

• 얼마나 엄격히 타입 오류를 검사할 것인지?
• 컴파일 결과로 생성되는 자바스크립트 코드의 버전은 어떻게 할 것인지?
• etc..

 

이런 컴파일 옵션을 작성한 내용은 tsconfing.json에 작성하게 되고 이 파일은 타입스크립트 프로젝트의 root에 존재합니다.

 

tsconfig.json에서 옵션들을 미리 정의해 놓으면 컴파일 할때 명령어에 일일히 대상 파일이나 옵션을 지정하지 않아도 되어 tsc, tsx 같은 명령어를 그냥 실행하면 현재 폴더에 있는 설정 내용을 기준으로 소스들을 컴파일하는 작업을 실행하게 됩니다.

• 현재 폴더에 설정파일이 없다면 프로젝트내 상위 폴더로 검색해나가면서 찾아갑니다.

 

📌 컴파일러 옵션 자동 생성

tsc --init

• 기본 설정이 완료된 tsconfig.json 파일이 생성됩니다.

 

📖 컴파일러 속성 정리

 

1️⃣ files

프로그램에 포함할 허용 파일 목록을 지정합니다.

파일을 찾을 수 없으면 오류가 발생합니다.

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

• 파일 확장자까지 포함해주어야 합니다.
• files 속성은 밑에서 배울 exclude보다 우선순위가 높습니다.
• 이 옵션이 생략되면 include와 exclude 속성으로 컴파일 대상을 결정하게 됩니다.

 

2️⃣ extends

다른 tsconfig.json 파일의 설정들을 가져와 재사용할 수 있게 해줍니다.

• tsconfig.json 파일의 최상위에 위치합니다.

// config/another.json
{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

{
  "extends": "./configs/another",
  "compilerOptions": {
    "strictNullChecks": false
  },
  "files": [
  ]
}

• extends된 설정보다 현재 파일의 설정을 우선시합니다.

 

3️⃣ include

include 옵션은 tsc에게 컴파일 할 타입스크립트 파일의 범위와 위치를 알려주는 옵션입니다.

• 여러 파일이 있을 때 tsc 명령어를 각 파일에 입력하지 않아도 됩니다.
• files 속성과 처럼 컴파일할 파일들을 지정하는 속성이지만 와일드 카드 패턴으로 지정해줍니다.

 

{
  "include": ["src"]
}

• src 폴더 아래의 모든 타입스크립트 파일이 동시에 컴파일

 

🖥️ 실행해보기

tsc

• src 디렉토리 안에 있는 타입스크립트 파일들이 컴파일되어 js 파일들이 생성되었습니다.

 

⚠️ 주의

• include에 명시되어 있어도 exclude에도 명시되어 있으면 제외됩니다.

 

4️⃣ exclude

컴파일 대상에서 제외할 파일들을 지정하는 속성

"exclude": [
  "node_modules", // node_modules 제외
]

 

5️⃣ compilerOptions

컴파일 대상 파일들을 어떻게 변환할지 세세히 정하는 옵션이다.

• "compilerOptions" 속성은 생략될 수 있으며 생략시 기본 값이 사용됩니다.

 

📖 와일드카드 패턴

1️⃣ *

• 0개 이상의 문자와 일치
• 단, 디렉토리 구분 기호(예: / 또는 )는 포함하지 않음
• 즉, 해당 디렉토리에 있는 모든 파일

2️⃣ ?

• 디렉토리 구분 기호는 포함하지 않음
• 즉, 해당 디렉토리에 있는 파일들의 이름 중 한 글자라도 포함하면 해당

3️⃣ **

• 0개 이상의 디렉토리 이름과 일치 모든 중첩 경로 포함
• 여러 계층에 걸쳐 중첩된 디렉토리도 모두 포함함
• 즉, 해당 디렉토리의 하위 디렉토리의 모든 파일을 포함
• 예: src/**/index.js는 src/index.js, src/app/index.js, src/app/test/index.js 모두에 일치

 

⭐ compilerOptions 옵션 정리

 

🎯 target 옵션

컴파일 결과 생성되는 자바스크립트 코드의 버전을 설정하는 옵션

{
  "compilerOptions": {
    "target": "ES5"
  },
  "include": ["src"]
}

 

🖥️ 실행

const func = () => console.log("Hello, World!");

var func = function () {
  return console.log('Hello, World!');
};

• target 옵션을 ES5로 설정했기 때문에 컴파일 과정에서 화살표 함수 같은 ES6의 문법이 ES5의 문법으로 변환

 

✅ 최신 자바스크립트 버전으로 설정

"compilerOptions": {
  "target": "ESNext"
},

 

컴파일 결과

const func = () => console.log('Hello, World!');

 

🧩 module 옵션

변환되는 자바스크립트 코드의 모듈 시스템을 설정하는 옵션

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS"
  },
  "include": ["src"],
  "exclude": ["node_modules"]
}

• module 옵션을 추가한 후 CommonJS를 설정

 

🖥️ 실행

// test.js
export const test = () => {
  console.log("test");
};

--------------
// index.ts
import { test } from './test';
console.log(test);

// test.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.test = void 0;
const test = () => {
    console.log('test');
};
exports.test = test;

// index.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const test_1 = require("./test");
console.log(test_1.test);

컴파일 결과 require나 exports 등의 CommonJS 문법으로 코드가 변환된 것을 확인할 수 있습니다.

 

📂 outDir

컴파일 결과 생성할 자바스크립트 코드의 위치를 결정하는 옵션

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "outDir": "dist"
  },
  "include": ["src"]
}

tsc를 이용해 컴파일 하면 이제 컴파일 결과가 dist 폴더에 생성됩니다.

 

🖥️ 실행

 

⚠️ strict

타입스크립트 컴파일러의 타입 검사 엄격함 수준을 정하는 옵션

이전의 test.ts를 수정했습니다.

export const test = (message) => {
  console.log('test ' + message);
};

strict 옵션을 true로 설정합니다.

 

{
  "compilerOptions": {
    ...
    "strict": true
  },
  "include": ["src"]
}

그리고 test.ts를 살펴보면 오류가 있다는 것을 알려줍니다!!

 

• strict 옵션을 true로 설정하면 이제 코드를 아주 엄격하게 검사하기 때문입니다!

 

타입스크립트에서는 매개변수의 타입은 프로그래머가 직접 지정하도록 권장.

• 타입을 직접 지정하지 않을 경우 엄격한 타입 검사 모드에서는 오류가 발생
• 타입스크립트는 함수 매개변수의 타입을 자동추론할 수 없기 때문입니다

 

🧩 ModuleDetection 옵션

타입스크립트의 모든 파일은 기본적으로 전역 파일(모듈)로 취급됩니다.

따라서 a.ts와 b.ts 두 타입스크립트 파일에서 동일한 이름의 변수를 선언하면 오류가 발생합니다.

// a.ts
const a = 1; // ❌

// b.ts
const a = 1; // ❌

이럴 때에는 각 파일에 모듈 시스템 키워드(export, import)를 사용해 파일을 전역 모듈이 아닌 로컬모듈로 취급되도록 만들어야 합니다.

 

이를 자동화 하는 옵션이 바로 moduleDetection 옵션입니다.

• moduleDection 옵션을 force로 설정할 경우 자동으로 모든 타입스크립트 파일이 로컬 모듈로 취급

 

{
  "compilerOptions": {
    ...
        "moduleDetection": "force"
  },
  "include": ["src"]
}

 

🗾 sourceMap

컴파일된 파일 디렉터리에 .js.map 파일이 만들어져 변환된 js 코드가 ts의 어디에 해당하는지를 알려줍니다.

{
  "compilerOptions": {
    ...
    "sourceMap": true
  },
  "include": ["src"]
}

• 디버깅 작업에 매우 유용

 

 

🌐 브라우저에서 개발자 모드로 확인

타입스크립트 프로젝트를 배포후 source 탭을 확인해보면 브라우저는 js만 인식하지만 이 매핑 파일에 의해 ts 파일을 인식합니다.

 

📚 Ref.

https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#handbook-content

https://www.typescriptlang.org/tsconfig/

https://typescript-kr.github.io/pages/compiler-options.html

https://inpa.tistory.com/entry/TS-📘-타입스크립트-tsconfigjson-설정하기-총정리

https://ts.winterlood.com/e7ec2f43-9d8c-4d30-bb2c-29e1b57f6a39