configuration

1. default settings

JavaScript Engine은 TypeScript 코드를 읽을 수 없기 때문에, TypeScript 코드를 JavaScript 코드로 transpile 해야 한다.
(transpile이라는 표현이 적절하지만, 관용적으로 compile이라고도 표현한다)

코드 변환을 수행하기 위해 전역적으로, 혹은 프로젝트 내에서 typescript 패키지를 설치할 필요성이 있다.
다음과 같이 택일하여 설치한다.

npm i -g typescript  # 전역
npm i -D typescript  # 로컬

이후 특정 TypeScript 파일을 JavaScript 파일로 변환하기 위해 다음과 같은 명령을 사용한다.
만약 로컬로만 설치했을 경우, terminal이 tsc 명령을 이해하지 못할 수 있는데, 앞에 npx 키워드를 붙여 실행하면 해결된다.

# index.ts 파일을 변환할 경우
tsc index.ts
npx tsc index.ts

혹은 프로젝트 내 파일 변화를 감시하여, 자동으로 변환되도록 하고 싶을 경우 다음과 같은 명령을 사용한다.

tsc --watch
npx tsc --watch

2. version management

node.js version에 따라 내장 메서드가 추가되거나 deprecated 될 수 있다.
또한 node.js가 제공하는 기능의 인터페이스 역시 major version이 변화함에 따라 변경될 수 있다.
따라서 node.js version과 typescript version, 그리고 @types/node version이 서로 호환되록 맞추는 것이 중요하다.

만약 버전이 달라 무언가 서로 호환되지 않을 경우, 다음과 같은 오류가 발생할 수 있다.

node_modules/@types/node/crypto.d.ts:3570:17 - error TS1110: Type expected.
3570     type UUID = `${string}-${string}-${string}-${string}-${string}`;
                     ~~~
node_modules/@types/node/test.d.ts:1073:34 - error TS1005: '?' expected.
1073             : F extends abstract new(...args: any) => infer T ? T
                                      ~~~
node_modules/@types/node/test.d.ts:1073:63 - error TS1005: ':' expected.
1073             : F extends abstract new(...args: any) => infer T ? T
                                                                   ~
node_modules/@types/node/test.d.ts:1074:13 - error TS1005: ',' expected.
1074             : unknown,
                 ~
(생략)

version을 맞추기 위해서는, 실행하는 환경의 node.js version을 먼저 살펴보는 것이 좋다.
이때 nvm을 이용한다면 좀 더 편리하게 node.js version을 관리할 수 있다.

node --version

TypeScript 공식문서를 통해 어떤 node.js version이 지원되는지 확인할 수 있다.
예를 들어 TypeScript 5 version의 경우 ECMA2018(node.js 10 and later) version부터 지원된다.

한 가지 더 알아둘 점이 있다면, 실행 환경의 node.js major version과 @types/node의 major version을 일치시키는게 좋다.
만약 20.15.1 version의 node.js를 사용하고 있다면, major version이 20인 “@types/node”를 이용하는 식이다.

경험상 package.json에서 version을 지정할 때 다음과 같이 지정하는 것이 경험상 오류없이 잘 동작하였다. create-next-app이 TypeScript의 version을 지정하는 방식인데, caret(^)을 통해 간편하게 version 관리를 설정했음을 볼 수 있다.

// package.json
{
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20"
  }
}