TypeScript 시작하기:tsconfig.json과 ts-node 이해하기

주로 온라인 에디터나 Vite를 통해 TypeScript를 사용했었다. 이번에는 TypeScript를 설치하고 실행 환경을 구성하면서 기본적인 설정과 사용 방법을 헷갈리지 않게 깔끔하게 정리하려고 한다.

1.npm으로 타입스크립트 컴파일러 등 설치

npm init으로 노드 js패키지를 초기화하고 타입스크립트가 node.js의 전역객체, 모듈의 타입 등을 알기 위해 @types/node를 설치합니다. ts-node는 ts파일을 바로 실행해 주는 도구로 tsc를 통해 ts파일을 js파일로 컴파일할 필요 없이 바로 실행해 주는 도구이다.

npm init
npm i @types/node
npm i typescript -g
npm i ts-node -g

아래 명령어를 통해 타입스크립트 컴파일러가 잘 설치되었는지 버전을 확인한다.

tsc -v

2.tsconfig 생성과 설정방법

아래 명령어를 입력하면 타입스크립트 관련 설정에 대한 tsconfig.json이 생긴다.

npx tsc --init

src폴더를 만들어주고 ts파일을 작성해 준 뒤 아래 적힌 명령어를 실행하면 ts파일이 js파일로 컴파일된다.

(src폴더 말고 본인이 원하는 폴더구조, 그냥 상단에 ts파일을 두거나 해도 된다.)

tsc src/index.ts

위에 tsc명령어를 통해 타입스크립트를 자바스크립트로 컴파일하여 사용할 수 있다.

tsc를 하고 나면 해당경로에 js파일이 생긴 것을 볼 수 있다.

2-1. include

tsconfig관련 설정에 대해 정리하려고 한다.

  "include": ["src"]

include는 프로젝트 특정 폴더 경로에 ts파일을 컴파일할 거라고 설정해 주는 부분으로 "include":["src"] 작성하면 src안에 있는 ts파일을 한 번에 컴파일할 수 있다.

tsc

include를 사용해서 컴파일해야 하는 범위를 정해주었기 때문에 tsc만 입력해도 컴파일이 된다

2-2. compilerOptions

compilerOptions는 TypeScript 컴파일러(tsc)의 동작 방식을 설정하는 옵션들을 모아놓는 객체이다.

-target

target은 TypeScript 코드를 컴파일할 때 출력할 JavaScript의 ECMAScript 버전을 지정하는 옵션이다.

{
  "compilerOptions": {
    "target": "es2025"
  }
}

예를 들어:

const add = (a: number, b: number) => a + b;

target이 오래된 버전이라면 최신 문법을 하위 버전 문법으로 변환할 수 있고,

{
  "target": "es5"
}

화살표 함수가 일반 함수로 변환된다.

var add = function (a, b) {
  return a + b;
};

반면 최신 버전인:

{
  "target": "es2025"
}

를 사용하면 최신 문법을 거의 그대로 유지한 채 출력한다.

const add = (a, b) => a + b;

-module

module은 TypeScript가 import와 export를 어떤 모듈 시스템 형식으로 출력할지 결정하는 옵션이다.

Node.js를 사용하다 보면 아래와 같이 import/export 또는 require 문법을 사용하는 코드를 볼 수 있는데, 이러한 모듈 시스템을 TypeScript가 어떤 형식으로 변환할지 설정하는 역할을 한다.

import { add } from "./math.js";
const { add } = require("./math");

예를 들어 module을 "esnext"로 설정하면 TypeScript는 컴파일 결과를 최신 ES Module(ESM) 형식으로 출력한다.

{
  "compilerOptions": {
    "module": "esnext"
  }
}

다음 TypeScript 코드가 있다고 가정해 보자.

import { add } from "./math.js";

export const result = add(1, 2);

컴파일 후에도 import와 export 문법이 그대로 유지된다.

import { add } from "./math.js";

export const result = add(1, 2);

반대로 module을 "commonjs"로 설정하면 CommonJS 형식으로 변환된다.

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

동일한 TypeScript 코드는 다음과 같은 JavaScript 코드로 출력된다.

const { add } = require("./math");

exports.result = add(1, 2);

따라서 module 옵션은 TypeScript 코드의 모듈을 어떤 JavaScript 모듈 시스템 형식으로 출력할지 결정하는 설정이라고 이해하면 된다.

-rootDir, outDir

rootDir과 outDir은 TypeScript 프로젝트의 소스 코드와 컴파일 결과물을 관리하기 위한 옵션이다.

• rootDir : 컴파일 시 폴더 구조를 유지할 기준 경로
• outDir : 컴파일된 JavaScript 파일이 저장될 경로

예를 들어 다음과 같은 프로젝트 구조가 있다고 가정해 보자.

src
├─ index.ts
└─ utils
   └─ math.ts

그리고 tsconfig.json에 아래와 같이 설정한다.

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  }
}

TypeScript는 rootDir로 지정된 src 폴더를 기준으로 디렉터리 구조를 분석한 뒤, 컴파일된 결과물을 outDir로 지정된 dist 폴더에 출력한다. 컴파일이 완료되면 src폴더구조와 동일하게 아래와 같은 구조가 생성된다.

dist
├─ index.js
└─ utils
   └─ math.js

위 결과를 보면 src 내부의 폴더 구조가 그대로 유지된 채 TypeScript 파일만 JavaScript 파일로 변환되어 출력된 것을 확인할 수 있다. 따라서 rootDir은 단순히 소스 코드가 위치한 폴더를 의미하는 것이 아니라, 컴파일 과정에서 폴더 구조를 유지할 기준 경로를 지정하는 역할을 한다. 그리고 outDir은 이렇게 생성된 컴파일 결과물을 저장할 위치를 지정한다.

일반적으로 src 폴더에 TypeScript 소스 코드를 작성하고, dist 폴더에 컴파일된 JavaScript 파일을 출력하는 구조를 사용한다. 이를 통해 원본 소스 코드와 빌드 결과물을 명확하게 분리하여 관리할 수 있다.

-strict

  "compilerOptions": {
    "strict": true
  }

strict는 타입스크립트의 엄격한 타입 검사 모드를 활성화하는 옵션이다.

타입 안정성을 높이기 위해 대부분 strict: true를 사용하는 편이다.

-moduleDetection

타입스크립트는 전역 스코프를 보기 때문에 같은 경로에 있는 ts파일에 동일한 변수명이 있다거나 하면 같은 스크립트로 처리되면서 전역 변수 충돌이 발생할 수 있다. 그래서 moduleDetection을 사용하여 모듈로 판단할지 스크립트로 판단할지 결정하는 옵션이다.

{
  "compilerOptions": {
    "moduleDetection": "force"
  }
}

moduleDetection을 force로 설정하면 모듈로 인식하여 각 파일이 독립적인 스코프를 가지기 때문에 변수명이 동일하여 충돌되는 문제를 방지할 수 있다.

 

3.ts-node사용법

위에서 살펴본 것처럼 TypeScript 파일을 실행하려면 일반적으로 tsc 명령어를 사용하여 JavaScript 파일로 컴파일한 뒤, Node.js로 실행해야 한다. 하지만 매번 컴파일 과정을 거치는 것은 개발 중에 다소 번거로울 수 있다.

이때 ts-node를 사용하면 TypeScript 파일을 별도의 컴파일 과정 없이 직접 실행할 수 있어서 편리하며 내부적으로 변환되어 실행되기 때문에 프로젝트에 tsc와 다르게 js파일이 안 생긴다.

ts-node src/index.ts

위에 명령어대로 ts-node 적고 경로 작성해 주면 된다.

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

ts-node를 사용하기 전 마찬가지로 tsconfig.json에 설정해야 되는 옵션이 있다.

ts파일을 ES Module(ESM) 방식으로 실행하라는 옵션으로 위에서 설명한 module: "esnext"를 ts-node가 정상적으로 실행할 수 있게 해 준다. true로 해두면 현재 프로젝트를 ES Module 환경으로 실행하라고 알려주는 설정이다.

https://san2-dev.tistory.com/12

1. TypeScript 기초입문) 변수,함수,배열 사용하는 방법