1.2 설치 및 환경 설정

TypeScript로 개발을 시작하려면 몇 가지 도구를 설치해야 한다. TypeScript 컴파일러 자체는 Node.js 패키지로 배포되므로 Node.js 환경이 먼저 필요하다. 이 장에서는 TypeScript 개발 환경을 처음부터 구성하는 전 과정을 단계별로 다룬다.

Node.js 설치 확인

TypeScript 컴파일러(tsc)와 관련 도구들은 모두 Node.js 환경에서 동작한다. 터미널을 열고 다음 명령으로 설치 여부를 확인한다.

node -v
# v20.x.x 이상이어야 한다

npm -v
# 10.x.x 이상 권장

Node.js가 설치되어 있지 않다면 nodejs.org에서 LTS(Long Term Support) 버전을 다운로드한다. TypeScript 5.x는 Node.js 14.17 이상을 요구하지만, 실무에서는 Node.js 20 LTS를 사용하는 것이 권장된다.

여러 Node.js 버전을 관리해야 한다면 nvm(Node Version Manager)을 사용한다.

# nvm으로 Node.js 20 LTS 설치
nvm install 20
nvm use 20
node -v  # v20.x.x

TypeScript 설치 방법

TypeScript를 설치하는 방법은 크게 전역 설치와 로컬 설치 두 가지다.

전역 설치

시스템 어디서나 tsc 명령어를 직접 사용할 수 있다. 간단한 실습이나 스크립트 작성에 편리하다.

npm install -g typescript

# 설치 확인
tsc -v
# Version 5.x.x

로컬 설치 (실무 권장)

프로젝트 디렉토리에만 TypeScript를 설치한다. devDependencies에 기록되어 팀원이 npm install을 실행하면 동일한 버전을 사용하게 된다.

npm install --save-dev typescript

# 버전 확인 (npx를 통해 로컬 tsc 실행)
npx tsc -v
# Version 5.x.x

실무 프로젝트에서는 로컬 설치가 필수다. 팀원마다 전역으로 설치된 TypeScript 버전이 다르면 컴파일 결과가 달라지는 문제가 생긴다. 로컬 설치 + package.json 스크립트를 사용하면 이 문제를 방지할 수 있다.

npx tsc — 로컬 tsc 실행

npx는 로컬에 설치된 패키지의 CLI를 실행하는 도구다. 로컬로 TypeScript를 설치한 경우 tsc 대신 npx tsc를 사용한다.

npx tsc --version    # 로컬 TypeScript 버전 확인
npx tsc hello.ts     # hello.ts 파일 컴파일
npx tsc              # tsconfig.json 기준으로 프로젝트 전체 컴파일
npx tsc --watch      # 파일 변경 감지 후 자동 재컴파일
npx tsc --init       # tsconfig.json 생성

tsc 기본 사용법

TypeScript 컴파일러의 기본 사용 패턴을 익혀 두면 개발 흐름을 이해하는 데 도움이 된다.

단일 파일 컴파일

tsc hello.ts

hello.ts를 컴파일해 같은 디렉토리에 hello.js를 생성한다. 타입 오류가 있으면 에러 메시지를 출력하지만 기본적으로 .js 파일은 여전히 생성된다.

프로젝트 전체 컴파일

tsconfig.json이 있는 디렉토리에서 tsc만 실행하면 설정 파일 기준으로 프로젝트 전체를 컴파일한다.

tsc
# tsconfig.json을 읽어 설정에 따라 컴파일

감시 모드 (Watch Mode)

개발 중에는 파일을 수정할 때마다 자동으로 재컴파일되는 감시 모드가 편리하다.

tsc --watch
# 또는
tsc -w

파일을 저장하는 순간 터미널에 컴파일 결과가 즉시 표시된다.

타입 검사만 수행

JavaScript 파일을 생성하지 않고 타입 오류만 확인한다. CI/CD 파이프라인에서 자주 사용한다.

tsc --noEmit

ts-node — TypeScript 직접 실행

tsc는 TypeScript를 JavaScript로 컴파일한 다음, 별도로 node로 실행해야 한다. 두 단계를 거쳐야 하는 번거로움이 있다. ts-node는 이 두 단계를 하나로 합쳐 TypeScript 파일을 직접 실행한다.

ts-node 설치

# 전역 설치
npm install -g ts-node

# 로컬 설치 (권장)
npm install --save-dev ts-node

ts-node 사용

# TypeScript 파일 바로 실행
ts-node src/index.ts

# 로컬 설치 시
npx ts-node src/index.ts

ts-node 동작 방식

ts-node는 내부적으로 TypeScript 컴파일러를 호출해 메모리에서 컴파일하고 즉시 실행한다. 디스크에 .js 파일을 생성하지 않는다. 개발 중 빠른 피드백 루프를 만들어 준다.

단점은 속도다. 컴파일 시간이 길어 대형 프로젝트에서는 체감될 수 있다. 또한 TypeScript 5.x의 최신 기능이나 ESM(ES Modules) 지원이 제한적인 경우가 있다.

tsx — 더 빠른 대안

tsx는 ts-node의 빠른 대안이다. 내부적으로 esbuild를 사용해 TypeScript를 변환한다. esbuild는 Go로 작성된 번들러로 기존 JavaScript 기반 도구보다 수십 배 빠르다.

tsx 설치

# 전역 설치
npm install -g tsx

# 로컬 설치 (권장)
npm install --save-dev tsx

tsx 사용

# TypeScript 파일 바로 실행
tsx src/index.ts

# 감시 모드 (파일 변경 시 자동 재실행)
tsx watch src/index.ts

# 로컬 설치 시
npx tsx src/index.ts

tsx의 장점

tsx는 ESM(ES Modules)을 기본으로 지원한다. import/export 문법을 사용하는 최신 코드를 추가 설정 없이 실행할 수 있다. 또한 타입 검사를 수행하지 않고 변환만 하기 때문에 속도가 매우 빠르다.

주의할 점은 tsx가 타입 검사를 건너뛴다는 것이다. 빠른 실행을 위해 타입 오류를 무시한다. 따라서 타입 안전성 확인은 별도로 tsc --noEmit으로 수행해야 한다.

ts-node vs tsx 비교

항목	ts-node	tsx
실행 속도	느림	빠름 (esbuild 기반)
타입 검사	수행	건너뜀
ESM 지원	설정 필요	기본 지원
CJS 지원	기본 지원	지원
감시 모드	지원	tsx watch로 지원
tsconfig 반영	반영	반영
주 용도	개발/스크립트	개발/스크립트

개발 환경에서 빠른 피드백을 원한다면 tsx를 권장한다. 타입 검사는 IDE와 tsc --noEmit으로 별도 수행하면 된다.

프로젝트 초기화 워크플로우

새 TypeScript 프로젝트를 처음부터 만드는 전체 과정을 따라가 본다.

1단계: 디렉토리 생성 및 npm 초기화

mkdir my-ts-project
cd my-ts-project
npm init -y

npm init -y는 모든 질문에 기본값으로 답해 package.json을 즉시 생성한다.

2단계: 의존성 설치

npm install --save-dev typescript tsx @types/node

• typescript: TypeScript 컴파일러
• tsx: 빠른 TypeScript 실행 도구
• @types/node: Node.js 내장 모듈(fs, path, process 등)의 타입 정의

3단계: tsconfig.json 생성

npx tsc --init

프로젝트 루트에 tsconfig.json이 생성된다. 수백 줄의 주석과 함께 기본 옵션들이 담겨 있다.

4단계: 디렉토리 구조 생성

mkdir src dist

소스 파일은 src/, 컴파일 결과물은 dist/에 분리한다.

5단계: package.json 스크립트 추가

package.json을 열고 scripts 항목을 수정한다.

{
  "scripts": {
    "build": "tsc",
    "build:watch": "tsc --watch",
    "dev": "tsx watch src/index.ts",
    "start": "node dist/index.js",
    "type-check": "tsc --noEmit"
  }
}

이제 다음 명령으로 개발 작업을 진행할 수 있다.

npm run dev          # 개발 서버 (tsx watch, 빠른 실행)
npm run build        # 프로덕션 빌드 (tsc 컴파일)
npm run type-check   # 타입 오류만 확인

6단계: 기본 소스 파일 작성

// src/index.ts
const message: string = "TypeScript 프로젝트가 시작되었습니다!";
console.log(message);

최종 프로젝트 구조

my-ts-project/
├── src/
│   └── index.ts        # TypeScript 소스 파일
├── dist/               # 컴파일 결과물 (자동 생성)
│   └── index.js
├── node_modules/
├── package.json
├── package-lock.json
└── tsconfig.json

실전 예제: 간단한 TypeScript 프로젝트 세팅

실제 프로젝트와 같은 환경을 처음부터 구성한다.

# 1. 프로젝트 초기화
mkdir ts-starter && cd ts-starter
npm init -y

# 2. 의존성 설치
npm install --save-dev typescript tsx @types/node

# 3. tsconfig.json 생성
npx tsc --init

# 4. 소스 디렉토리 생성
mkdir src

tsconfig.json에서 핵심 옵션을 설정한다.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

package.json 스크립트를 추가한다.

{
  "name": "ts-starter",
  "version": "1.0.0",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.0.0"
  }
}

첫 소스 파일을 작성한다.

// src/index.ts
interface Person {
  name: string;
  age: number;
}

function greet(person: Person): string {
  return `안녕하세요, ${person.name}님! 나이는 ${person.age}세군요.`;
}

const user: Person = {
  name: "김철수",
  age: 28,
};

console.log(greet(user));

실행한다.

npm run dev
# 안녕하세요, 김철수님! 나이는 28세군요.

프로덕션 빌드를 생성한다.

npm run build
# dist/index.js 파일이 생성된다
node dist/index.js
# 안녕하세요, 김철수님! 나이는 28세군요.

고수 팁

프로젝트별 TypeScript 버전을 고정하라

package.json에 TypeScript 버전을 정확하게 명시해 팀 전체가 동일한 버전을 사용하도록 한다.

{
  "devDependencies": {
    "typescript": "5.4.5"
  }
}

^5.0.0처럼 캐럿(^)을 사용하면 마이너 업데이트가 자동으로 적용된다. TypeScript는 마이너 버전에서도 타입 검사 동작이 달라질 수 있으므로 실무에서는 정확한 버전을 고정하는 것이 안전하다.

tsx는 타입 검사를 하지 않는다

tsx로 실행이 잘 된다고 해서 타입이 올바른 것은 아니다. 타입 오류가 있어도 tsx는 실행한다. CI/CD나 배포 전에 반드시 tsc --noEmit으로 타입 검사를 별도로 수행한다.

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "type-check": "tsc --noEmit",
    "build": "npm run type-check && tsc"
  }
}

build 스크립트에서 타입 검사를 먼저 실행하고, 통과한 경우에만 컴파일하는 패턴이다.

.gitignore에 컴파일 결과물을 추가하라

# .gitignore
node_modules/
dist/
*.js.map

dist/ 폴더는 소스 코드에서 자동으로 생성되므로 버전 관리에 포함할 필요가 없다. npm run build로 언제든 재생성할 수 있다.

정리

도구	설치	용도
typescript	npm i -D typescript	TypeScript 컴파일러 (tsc)
ts-node	npm i -D ts-node	TS 직접 실행 (타입 검사 포함)
tsx	npm i -D tsx	TS 빠른 실행 (타입 검사 생략)
@types/node	npm i -D @types/node	Node.js 타입 정의
npx tsc --init	—	tsconfig.json 생성
tsc --watch	—	파일 변경 감지 자동 컴파일
tsc --noEmit	—	타입 검사만 수행

다음 장에서는 tsconfig.json의 핵심 옵션들을 자세히 살펴본다.