[TypeScript] 2. 개발 환경 세팅 (tsc, tsx, 에디터 설정)

이 글의 목표: 내 컴퓨터에서 .ts 파일을 직접 실행해보기. 컴파일러의 동작 원리도 함께 이해합니다.

 

준비물: Node.js

TypeScript 도구들은 Node.js 위에서 돌아갑니다. nodejs.org에서 LTS 버전을 설치하고 확인합니다.

node -v   # v20.x 이상이면 충분
npm -v

프로젝트 초기화

mkdir ts-study && cd ts-study
npm init -y                      # package.json 생성
npm install -D typescript        # 컴파일러를 프로젝트 로컬에 설치 (-D = 개발 의존성)

전역(-g) 설치보다 프로젝트 로컬 설치를 권장합니다. 프로젝트마다 TypeScript 버전이 다를 수 있기 때문입니다.

tsc: TypeScript 컴파일러

tsc(TypeScript Compiler)는 .ts를 .js로 변환합니다. 첫 파일을 만들어봅시다.

// src/hello.ts
const message: string = "Hello, TypeScript!";
console.log(message);

컴파일하고 실행합니다.

npx tsc src/hello.ts   # src/hello.js 가 생성됨
node src/hello.js      # Hello, TypeScript!

npx는 로컬에 설치한 도구를 실행해주는 명령입니다.

tsconfig.json: 컴파일러 설정 파일

파일마다 옵션을 넘기는 건 번거롭습니다. 설정 파일을 만들면 프로젝트 전체에 적용됩니다.

npx tsc --init   # tsconfig.json 생성

핵심만 담은 최소 설정은 다음과 같습니다.

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",        // 어떤 JS 버전으로 변환할지
    "module": "commonjs",      // 모듈 시스템 (Node 기본값)
    "rootDir": "./src",        // 소스 코드 위치
    "outDir": "./dist",        // 컴파일 결과물 위치
    "strict": true,            // 엄격한 타입 검사 (반드시 켜자!)
    "esModuleInterop": true    // import/require 호환성 개선
  }
}

이제 파일명을 지정하지 않고 tsc만 실행하면, src/의 모든 .ts를 컴파일해 dist/에 넣습니다.

npx tsc          # 전체 컴파일
npx tsc --watch  # 파일이 바뀔 때마다 자동 재컴파일 (개발 중 아주 유용)

strict: true는 초보에게 처음엔 까다롭게 느껴지지만, TypeScript를 제대로 배우는 유일한 길입니다. 끄지 마세요. (자세한 내용은 15편에서 다룹니다.)

컴파일 없이 바로 실행: tsx

매번 컴파일 → 실행 두 단계를 거치는 게 번거로울 때가 있습니다. .ts를 곧바로 실행하고 싶다면 tsx를 씁니다. tsx는 esbuild 기반이라 빠르고, 별도 설정 없이 바로 동작합니다.

npm install -D tsx
npx tsx src/hello.ts   # 컴파일 결과물 없이 즉시 실행

파일이 바뀔 때마다 자동으로 다시 실행하고 싶다면 watch 모드를 씁니다.

npx tsx watch src/hello.ts

학습이나 간단한 스크립트에는 tsx가 편하고, 실제 배포에는 tsc로 빌드한 결과물을 씁니다.

왜 ts-node가 아니라 tsx인가?
예전에는 같은 용도로 ts-node를 많이 썼습니다. 하지만 ts-node는 최신 TypeScript 버전과 맞물릴 때 Cannot read properties of undefined (reading 'fileExists') 같은 호환성 에러를 내는 경우가 있고, 시작 속도도 느립니다. 요즘 새 프로젝트에서는 tsx가 사실상 표준 대체재입니다. 만약 ts-node로 위 에러를 만났다면, tsx로 갈아타는 것이 가장 간단한 해결책입니다.

참고: Node.js 자체 실행

최신 Node.js(v22.18 이상, v24 LTS부터는 기본 활성화)는 별도 도구 없이 .ts 파일을 직접 실행할 수 있습니다. 타입 표기만 지우고(type stripping) 실행하는 방식입니다.

node src/hello.ts   # 최신 Node에서는 이것만으로 실행된다

다만 이 방식은 타입 검사를 하지 않고, enum·데코레이터 같은 일부 문법은 지원하지 않습니다. 간단한 스크립트에는 편리하지만, 타입 검사가 필요하면 여전히 tsc(또는 tsx + tsc --noEmit)를 함께 씁니다. Node 버전에 따라 동작이 다르므로, 실제 사용 전 설치된 Node 버전을 확인하세요.

package.json에 스크립트 등록

명령을 매번 외우지 않도록 단축어를 만듭니다.

// package.json
{
  "scripts": {
    "build": "tsc",                    // npm run build
    "dev": "tsx src/hello.ts",         // npm run dev
    "watch": "tsc --watch"             // npm run watch
  }
}

npm run dev

에디터: VS Code

VS Code는 TypeScript를 기본 지원합니다(별도 설치 불필요). 몇 가지 설정만 추가하면 경험이 크게 좋아집니다.

// .vscode/settings.json
{
  // 저장할 때 자동으로 import 정리 & 포맷
  "editor.formatOnSave": true,
  // 저장할 때 사용하지 않는 import를 정리하고 순서를 정돈한다
  "editor.codeActionsOnSave": {
    // 값 옵션: "explicit"(Ctrl+S 등 직접 저장 시에만 실행, 기본값)
    //         "always"(직접 저장 + 창 전환 등 자동 저장 시에도 실행)
    //         "never"(저장 시 실행 안 함)
    "source.organizeImports": "explicit"
  },
  // 프로젝트에 설치된 TypeScript 버전 사용 (전역 버전과의 불일치 방지)
  "typescript.tsdk": "node_modules/typescript/lib"
}

정리

• tsc는 .ts → .js 컴파일러이며, 설정은 tsconfig.json에 모은다.
• strict: true는 반드시 켠다.
• 학습/스크립트에는 tsx(또는 최신 Node의 직접 실행)로 즉시 실행하고, 배포에는 tsc 빌드 결과물을 쓴다.
• npm run 스크립트로 명령을 단축한다.

이제 실행 환경이 준비됐으니, 다음 글부터 본격적으로 타입을 배웁니다.