개발 환경 설정

타입스크립트를 배울 때 생각보다 많은 시간이 드는 곳이 개발 환경입니다. 명령은 맞게 입력했는데 컴파일이 되지 않거나, 편집기에서는 멀쩡한데 터미널에서만 오류가 나면, 처음에는 내 코드가 틀렸다고 오해하기 쉽습니다. 이런 문제의 상당수는 컴파일러의 버전이나 설정 파일이 서로 어긋나서 생깁니다.

이 글은 Node.js와 npm, 타입스크립트 컴파일러, VS Code를 차례로 준비하고, tsconfig.json을 직접 써서 첫 프로젝트를 검사하고 컴파일해 실행합니다. 설치하는 순서뿐 아니라 각 단계가 왜 필요한지와 어디서 어긋나기 쉬운지도 함께 봅니다.

Node.js와 npm 준비하기

타입스크립트 컴파일러는 자바스크립트로 만든 프로그램이어서, 실행하려면 Node.js가 필요합니다. Node.js는 브라우저 밖에서 자바스크립트를 실행하는 런타임이고, 패키지를 설치하는 도구인 npm(Node Package Manager)이 함께 설치됩니다. 제공된 실습 환경에 이미 도구가 있다면 설치를 반복하지 말고 아래 명령으로 버전부터 확인합니다.

Node.js 공식 웹사이트에서 운영체제에 맞는 설치 파일을 내려받아 설치합니다. 특별한 이유가 없다면 오래 지원되는 LTS(Long Term Support) 버전을 고르고, 이 교재는 Node.js 24.21.0을 기준으로 실행 결과를 설명합니다. 다만 2026년 10월 28일부터 웹사이트가 먼저 권하는 LTS는 Node.js 26이고 24는 2028년 4월까지 지원되는 유지보수 단계의 LTS가 되었으므로, 본문과 같은 환경을 원하면 내려받을 때 24 버전대를 고릅니다. 설치가 끝나면 터미널을 새로 열고 두 도구의 버전을 확인합니다.

node -v
npm -v

첫 줄에 v24.21.0처럼 v로 시작하는 Node.js의 버전이, 둘째 줄에 npm의 버전이 나오면 준비가 끝난 것입니다. 명령을 찾을 수 없다는 메시지가 나오면, 설치한 뒤 터미널을 다시 열었는지 먼저 확인합니다.

npm 말고도 Yarn이나 pnpm 같은 패키지 관리자가 있지만, 이 교재의 실습은 npm만으로 따라 할 수 있습니다. 이미 다른 패키지 관리자를 쓰는 프로젝트라면 그 프로젝트가 정한 도구와 잠금 파일(lockfile)을 따르고, 한 프로젝트에서 두 패키지 관리자를 섞어 쓰지 않습니다.

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

타입스크립트 컴파일러는 typescript라는 npm 패키지에 들어 있고, tsc라는 명령으로 실행합니다. 이 교재의 앞부분 실습은 어느 폴더에서나 쓸 수 있도록 전역(global)으로 설치한 tsc를 쓰고, 테스트 도구나 프레임워크를 쓰는 뒤쪽 장은 프로젝트에 설치할 버전을 그 장에서 따로 밝힙니다.

npm install -g [email protected]
tsc -v

-g는 패키지를 프로젝트가 아니라 컴퓨터 전체에 설치하라는 옵션이고, [email protected]은 6.0 버전대 가운데 가장 최근 것을 고르라는 뜻입니다. 설치가 끝나면 tsc -v가 Version 6.0.으로 시작하는 한 줄을 출력합니다. 버전을 적어 둔 것은 이 교재가 6.0의 기본값과 진단을 기준으로 설명하기 때문이며, 다른 버전을 설치하면 일부 기본값과 진단이 본문과 다를 수 있습니다. 2026년 10월 현재 버전을 적지 않고 npm install -g typescript로 설치하면 Go로 다시 만든 7.0이 설치됩니다. 7.0은 기본값이 6.0과 같지만, 6.0에서는 "ignoreDeprecations": "6.0"으로 끌 수 있던 폐기 예정 옵션의 오류를 끌 수 없게 하고 그 옵션들을 더는 지원하지 않습니다.

전역 설치는 배우기에 간단하지만, 여러 사람이 함께 만드는 프로젝트에서는 사람마다 설치한 버전이 달라 같은 코드의 검사 결과가 달라질 수 있습니다. 그래서 실무에서는 프로젝트마다 컴파일러를 개발 의존성(devDependencies)으로 설치하고, 정확한 버전을 기록합니다.

npm install --save-dev --save-exact [email protected]
npx tsc -v

--save-exact는 package.json에 범위가 아닌 정확한 버전을 적고, npm은 실제로 설치한 패키지의 버전을 package-lock.json에 기록합니다. npx tsc는 이 프로젝트의 node_modules에 설치된 tsc를 실행하므로, 전역 tsc와 버전이 다를 수 있습니다. 다른 사람이 같은 버전을 받으려면 두 파일을 함께 보관하고, 잠금 파일에 적힌 그대로 설치하는 npm ci를 씁니다.

위 그림은 이런 협업용 흐름을 보여 줍니다. 프로젝트의 TypeScript 버전과 잠금 파일, 편집기가 쓰는 버전, tsconfig.json을 맞춘 뒤, 검사만 하는 단계와 오류가 없을 때만 출력하는 단계를 나누고, 마지막으로 실제 런타임에서 결과를 확인합니다. 이 글의 실습은 전역 tsc로 진행하지만, 같은 순서를 로컬 설치에도 그대로 쓸 수 있습니다.

편집기 준비하기

편집기는 Visual Studio Code(VS Code)를 권합니다. VS Code에는 타입스크립트 언어 서비스가 들어 있어서, 따로 설정하지 않아도 .ts 파일을 열면 문법 강조와 자동 완성, 타입 오류의 표시가 동작합니다.

다만 VS Code에 들어 있는 TypeScript의 버전은 컴퓨터에 설치한 tsc나 프로젝트에 설치한 버전과 다를 수 있고, 그러면 편집기의 오류와 tsc의 출력이 어긋날 수 있습니다. 프로젝트에 컴파일러를 로컬로 설치했다면, 명령 팔레트에서 TypeScript: Select TypeScript Version을 실행해 작업 영역(workspace)의 버전을 고릅니다. 이 과정은 VS Code의 TypeScript 안내에 설명되어 있습니다.

첫 프로젝트 만들기

새 폴더 ts-first를 만들고 VS Code로 엽니다. 이전 실습의 파일이나 출력과 섞이지 않도록, 기존 프로젝트가 아닌 빈 폴더에서 시작합니다.

mkdir ts-first
cd ts-first
code .

code .는 현재 폴더를 VS Code로 여는 명령이며, 이 명령이 동작하지 않으면 VS Code에서 폴더 열기 메뉴를 써도 됩니다. 폴더 안에 다음 세 파일을 만듭니다.

{
  "private": true,
  "type": "commonjs"
}

package.json은 Node.js와 npm이 이 폴더를 하나의 패키지로 읽는 파일입니다. "private": true는 실수로 npm에 공개되지 않게 막고, "type": "commonjs"는 이 폴더의 .js 파일을 CommonJS 모듈 방식으로 실행하라는 뜻입니다. 모듈 방식의 차이는 CommonJS와의 상호 운용성에서 자세히 다룹니다.

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "strict": true,
    "noEmitOnError": true,
    "outDir": "dist"
  },
  "include": ["index.ts"]
}

tsconfig.json은 컴파일러가 어떤 파일을 어떤 규칙으로 검사하고 출력할지 정하는 설정 파일입니다. target은 출력할 자바스크립트의 문법 수준, module은 Node.js의 모듈 규칙을 따를지, strict는 엄격한 검사를 켤지를 정합니다. noEmitOnError는 오류가 있으면 출력을 만들지 않게 하고, outDir은 출력 파일을 dist 폴더에 모으며, include는 이번에 검사할 파일을 index.ts 하나로 정합니다.

tsc --init 명령으로 설정 파일의 틀을 만들 수도 있습니다. TypeScript 5.9부터 이 명령은 자주 쓰는 권장 설정을 담은 짧은 파일을 만들며, 그 안에는 선언 파일과 소스 맵을 함께 출력하는 옵션도 켜져 있습니다. 만들어지는 내용은 버전마다 달라질 수 있으므로, 이 교재는 출력을 예측할 수 있도록 필요한 옵션만 직접 적고, 이미 있는 프로젝트의 설정 파일을 교재의 예제로 덮어쓰지 않습니다.

function greet(name: string): string {
  return `Hello, ${name}! Welcome to TypeScript!`;
}

const userName: string = "TypeScript Learner";
console.log(greet(userName));

세 파일을 저장했으면 터미널에서 검사와 출력, 실행을 차례로 합니다. -p .는 현재 폴더의 tsconfig.json을 프로젝트 설정으로 쓰라는 옵션입니다.

tsc -p . --noEmit
tsc -p .
node dist/index.js

Hello, TypeScript Learner! Welcome to TypeScript!

첫 명령은 파일을 만들지 않고 검사만 하며, 오류가 없으면 아무것도 출력하지 않습니다. 둘째 명령은 같은 검사를 한 뒤 dist/index.js를 만들고, 셋째 명령이 그 파일을 실행해 한 줄을 출력합니다. dist/index.js를 열면 다음처럼 타입 표기가 지워져 있습니다.

"use strict";
function greet(name) {
    return `Hello, ${name}! Welcome to TypeScript!`;
}
const userName = "TypeScript Learner";
console.log(greet(userName));

name과 반환값, userName에 붙였던 : string이 사라졌고, 기본으로 켜져 있는 alwaysStrict 설정 때문에 맨 위에 엄격 모드 지시문이 붙었습니다. node index.js가 아니라 node dist/index.js를 실행한 이유는, 출력 파일이 outDir로 정한 dist에 생기기 때문입니다. 설정 파일이 어떤 파일을 고르는지는 공식 tsconfig 안내에, 출력 위치는 공식 outDir 설명에 있습니다.

정리

• 타입스크립트 컴파일러는 Node.js에서 실행되므로 Node.js와 npm을 먼저 준비하고, node -v와 npm -v로 확인합니다.
• 이 교재는 TypeScript 6.0을 기준으로 하므로 npm install -g [email protected]으로 설치하고 tsc -v로 버전을 확인합니다.
• 협업하는 프로젝트는 컴파일러를 개발 의존성으로 정확한 버전에 고정하고, package-lock.json을 보관해 npm ci로 같은 버전을 받습니다.
• VS Code에 들어 있는 TypeScript는 프로젝트의 버전과 다를 수 있으므로, 로컬 설치를 했다면 작업 영역의 버전을 고릅니다.
• tsc -p . --noEmit은 검사만 하고, tsc -p .은 설정에 따라 출력하며, 실행은 outDir에 생긴 파일로 합니다.

연습 문제

1. 오류가 생긴 뒤의 출력

검사와 실행에 성공한 뒤, index.ts의 끝에 let age: number = "twenty";를 7번째 줄로 추가했습니다. tsc -p . --noEmit과 tsc -p .은 각각 무엇을 보여 주나요? 그다음 node dist/index.js를 실행한 결과는 이 수정이 검사를 통과했다는 뜻인가요?

2. 두 가지 tsc

전역으로 6.0을 설치한 컴퓨터에서, typescript를 5.9.3으로 고정한 다른 프로젝트를 받았습니다. 이 프로젝트에서 tsc -v와 npx tsc -v는 각각 어떤 버전을 보여 주나요? package.json의 "build": "tsc -p ." 스크립트를 npm run build로 실행하면 어느 쪽이 쓰이나요?

3. include를 지웠을 때

ts-first 폴더에 연습용 파일 practice.ts를 만들었는데, 이 파일에는 아직 타입 오류가 있습니다. tsconfig.json에서 include를 지우고 tsc -p .을 실행하면 dist/index.js는 새로 만들어지나요?

다음 글 첫 번째 타입스크립트 프로그램 작성에서는 이 프로젝트에 변수와 함수에 타입을 붙인 파일을 더하고, 타입 추론과 진단, 컴파일한 결과의 실행을 차례로 확인합니다.