Node.js 환경에서 타입스크립트 설치하기

이번에 Typescript를 처음 사용해보면서 Node.js 환경에서 Typescript를 설치하고 이를 실행해보는 과정을 정리하고자 합니다.

📌 타입스크립트 컴파일러 설치

타입스크립트는 컴파일러에 의해서 자바스크립트로 변환한 다음에 실행합니다.

컴파일 하기 위해 타입스크립트 패키지를 설치해줍니다.

 

npm install -g typescript

 

위 명령어를 실행하면 node_modules 폴더에

• tsc, tsserver 가 설치된 것을 확인할 수 있습니다.

 

 

📌 @types/node 설치하기

npm install @types/node

 

@types/node는 Node.js API(내장 모듈, 예: fs, path, http 등)에 대한 TypeScript 타입 정의 패키지입니다.

 

타입스크립트 코드는 코드 실행 전 타입 검사 과정을 거치게 됩니다.

이 때 타입이 선언되지 않은 코드를 만나게 되면 오류가 발생하게 되는데 Node.js 기본 기능 역시 타입 검사를 하기 때문에 이 기본 기능들의 타입을 별도로 선언하기 위해 이 패키지를 설치해야 합니다.

• fs, process, Buffer 등의 타입 인식 오류 없이 개발할 수 있도록 지원
• Node.js가 제공하는 기본 기능(내장 함수, 클래스 등)에 대한 타입 정보를 가지고 있습니다.

 

✅ 결과

node_modules
- @types/node

 

패키지의 node_modules 폴더에 @types 폴더가 생성

 

node_modules/@types/console.d.ts

declare module "console" {
    import console = require("node:console");
    export = console;
}
declare module "node:console" {
    import { InspectOptions } from "node:util";
    global {
        // This needs to be global to avoid TS2403 in case lib.dom.d.ts is present in the same build
        interface Console {

• 이와같은 Node.js가 기본적으로 제공하는 기능들에 대한 타입이 선언되어 있는 파일들이 존재

 

🖥️ 실행해보기

1️⃣ 실행할 타입스크립트 파일 생성

// index.ts
const message: String = 'Hello, World!';

console.log(message);

 

2️⃣ tsc로 컴파일후 실행

타입스크립트 컴파일러를 이용해 이 타입스크립트 코드를 컴파일

> tsc index.ts

• 위 명령어를 사용하면 ts 파일이 js 파일로 변환이 됩니다.

 

// index.js
var message = 'Hello, World!';
console.log(message);

 

3️⃣ 컴파일된 JS 파일 실행

node index.js

----------결과------------
Hello, World!

 

📌 TS-Node 이용해 실행하기

위에서는 타입스크립트 코드를 실행하기 위해 tsc를 이용해 타입스크립트 코드를 자바스크립트로 변환하고

변환된 자바스크립트 코드를 Node.js로 실행시켰습니다.

 

이것은 너무 귀찮은 작업이기 때문에 이번에는 명령어 한번으로 타입스크립트 코드를 바로 실행시켜주는 도구 ts-node를 적용해서 실행해보고자 합니다.

 

ts-node를 설치해 ts-node명령어를 통해 타입스크립트를 컴파일 단계없이 실행할 수 있게 합니다.

 

📖 ts-node

JIT을 통해서 typescript를 javascript로 변환하여 사전 컴파일없이 Node.js에서 TypeScript를 직접 실행할 수 있도록 합니다

 

npm install -g ts-node

 

🖥️ 실행

ts-node index.ts

 

💣 문제 발생

> ts-node index.ts
TypeError: Unknown file extension ".ts"

• .ts 확장자를 인식못하는 문제가 발생했어요.

 

💡 시도한 해결 방법

 

1️⃣ package.json

{
  "type": "module",
}

 

2️⃣ tsconfig.json

// tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true
  },
  "ts-node": {
    "esm": true,
    "experimentalSpecifier": true
  }
}

ESM 환경이기 때문에 "module": "ESNext"로 설정

 

"ts-node": {
    "esm": true,
}

 

이렇게 설정한 후 다시 시도!! ⇒ 결과는 같았습니다.

 

🫠 Reddit 댓글과 인프런 커뮤니티 글

여러 해결방법을 찾고자 구글링을 하다 여러 글을 확인해볼 수 있었습니다.

 

https://www.inflearn.com/news/1065346

https://www.reddit.com/r/typescript/comments/17vvlt7/tsnodedev_not_work_with_esm/

https://www.reddit.com/r/typescript/comments/17vvlt7/tsnodedev_not_work_with_esm/

 

여기서 2가지의 접근 방법을 확인할 수 있었습니다.

• tsx
• vite-node

🧩 TSX

• esbuild 기반의 TypeScript 실행기로써 ts-node의 대안
• 속도가 매우 빠르며 ESM/CommonJS 모두 지원

TSX 사용 방법

# 설치
npm i -D tsx

# 실행
npx tsx [파일명]

 

🧩 Vite-node

• Vite 기반의 TypeScript,JavaScript 실행기. Vite의 변환 파이프라인을 활용한다.
• 네이티브 ESM을 지원하며 Vite의 플러그인 생태계를 활용 가능하다.

 

vite-node 사용 방법

# 설치
npm i -D vite-node

# 실행
npx vite-node [파일명]

 

🚀 선택

저는 ESM을 사용해서 프로젝트를 진행하고 있으며 아직 Vite에 대해 제대로 학습하지 않은 상태라 vite-node 보다는 tsx를 사용하기로 했습니다!!

 

🖥️ 결과

npx tsx index.ts

 

 

문제 없이 실행이 된 것을 확인했습니다!!

 

📚 Ref.

https://www.typescriptlang.org/ko/docs/handbook/typescript-tooling-in-5-minutes.html

https://typestrong.org/ts-node/docs/

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

https://nodejs.org/api/deprecations.html#DEP0180

https://www.inflearn.com/news/1065346

https://www.reddit.com/r/typescript/comments/17vvlt7/tsnodedev_not_work_with_esm/