tsc와 tsconfigjson

앞으로 jQuery 타입 선언 분석에 들어가기 전에, 타입스크립트 프로젝트의 기본 설정인 tsconfig.json과 tsc 명령어의 역할을 먼저 짚고 넘어가자. 이 글은 실무에서 자주 사용하는 설정들을 중심으로, 그 의미와 활용법을 정리한다.

 

프로젝트 초기화

먼저 프로젝트 폴더를 만들고 tsconfig.json 파일을 생성한다.

$ mkdir jquery
$ cd jquery
$ npx tsc --init

 

이 명령어는 tsconfig.json 파일을 생성하면서 기본적인 컴파일 옵션을 함께 설정해준다.

tsconfig.json 기본 옵션 설명

생성된 tsconfig.json 파일은 기본적으로 다음과 같은 옵션을 포함한다:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

 

각 항목은 다음과 같은 의미를 갖는다:

• target: 어떤 버전의 JavaScript로 변환할지를 정한다. es2016은 let, const, Promise 등을 지원한다.
• module: 어떤 모듈 시스템을 사용할지 설정한다. commonjs는 Node.js에서 사용하는 방식이다.
• strict: 타입을 엄격하게 검사하도록 설정한다. 개발 초기부터 켜두는 것을 추천한다.
• esModuleInterop: CommonJS 모듈을 ES 모듈처럼 import할 수 있게 한다.
• skipLibCheck: 외부 타입 선언 파일(.d.ts)의 오류를 무시한다. 외부 라이브러리의 오류 때문에 개발이 중단되는 것을 방지한다.
• forceConsistentCasingInFileNames: import 경로에서 대소문자를 일관되게 사용하도록 강제한다.

이 외의 옵션들은 주석 처리되어 있으며, 필요에 따라 활성화해서 사용할 수 있다.

TypeScript 코드 작성 및 변환

hello.ts 파일을 만들어보자.

// hello.ts
let str: 'hello' = 'hello';
str = 'world'; // ❌ 에러 발생

 

이 코드는 str 변수의 타입이 'hello'로 고정되어 있으므로, "world"를 할당하면 타입 에러가 발생한다.

컴파일 실행

$ npx tsc

 

터미널에는 다음과 같은 에러가 출력된다:

error TS2322: Type '"world"' is not assignable to type '"hello"'

 

하지만 JS는 생성됨

// hello.js
"use strict";
let str = 'hello';
str = 'world';

 

이처럼 타입 에러가 발생하더라도 .js 파일은 생성된다.

tsc 옵션 추가 사용법

타입 에러가 있을 때 JS 파일을 생성하지 않도록 하려면 다음과 같은 명령어를 사용할 수 있다.

--noEmit

 

타입만 검사하고 JS는 생성하지 않음:

$ npx tsc --noEmit

 

--noEmitOnError

 

타입 에러가 있을 경우에만 JS 생성을 막음

$ npx tsc --noEmitOnError

 

이 두 옵션은 tsconfig.json 파일에 아래와 같이 추가해 항상 적용할 수 있다:

{
  "compilerOptions": {
    ...
    "noEmitOnError": true
  }
}

 

JSON 파일을 import하고 싶다면

Node.js 환경에서는 .json 파일을 import하는 경우가 흔하다. TypeScript에서도 이를 지원하려면 다음 옵션을 활성화해야 한다:

{
  "compilerOptions": {
    ...
    "resolveJsonModule": true
  }
}

 

이 옵션을 활성화하면 .json 파일을 마치 JavaScript 객체처럼 타입 추론까지 적용하면서 사용할 수 있다.