“TypeScript 배우고 싶은데 뭐부터 설치해야 해요?” 이 질문 정말 많이 받았어요. 저도 처음엔 Node.js, npm, TypeScript… 뭐가 뭔지 헷갈렸거든요. 오늘은 제가 삽질했던 경험을 바탕으로 가장 쉬운 방법을 알려드릴게요.

준비물 확인

TypeScript 개발에 필요한 것들:

1. 컴퓨터 (Windows, Mac, Linux 전부 가능)
2. 인터넷 (Node.js 다운로드용)
3. 코드 에디터 (VSCode 추천)
4. 30분 정도의 시간

돈 들어가는 건 하나도 없어요. 전부 무료입니다!

1단계: Node.js 설치

TypeScript를 사용하려면 Node.js가 필요해요. Node.js는 JavaScript를 브라우저 밖에서도 실행할 수 있게 해주는 프로그램이에요.

Windows 설치

1. https://nodejs.org 접속
2. “LTS” 버전 다운로드 (추천 버전, 2025년 기준 20.x 이상)
3. 다운로드한 파일 실행
4. “Next” 연타하면 끝

Mac 설치

1. https://nodejs.org 접속
2. “LTS” 버전 다운로드
3. .pkg 파일 실행하고 설치

또는 Homebrew 쓰면 더 간단해요:

brew install node

설치 확인

터미널(명령 프롬프트)을 열고 아래 명령어 입력:

node --version
npm --version

실행 결과:

버전 번호가 나오면 성공이에요! 숫자는 좀 달라도 괜찮습니다.

2단계: TypeScript 설치

Node.js를 설치하면 npm(Node Package Manager)도 함께 설치돼요. npm으로 TypeScript를 설치할 거예요.

전역 설치 (추천)

npm install -g typescript

-g 옵션은 “global”의 약자예요. 컴퓨터 어디서든 TypeScript를 쓸 수 있게 해줍니다.

설치 확인

tsc --version

실행 결과:

tsc는 TypeScript Compiler의 약자예요. TypeScript를 JavaScript로 변환해주는 프로그램입니다.

3단계: VSCode 설치 (선택사항이지만 강력 추천)

Visual Studio Code는 TypeScript 개발할 때 가장 좋은 에디터예요. Microsoft에서 만들었고 무료입니다.

1. https://code.visualstudio.com 접속
2. 다운로드 후 설치
3. 끝!

VSCode의 장점:

• TypeScript 자동완성 완벽 지원
• 타입 에러를 실시간으로 표시
• 디버깅 기능
• 확장 프로그램 엄청 많음

4단계: 첫 TypeScript 프로젝트 만들기

이제 본격적으로 프로젝트를 만들어볼게요.

프로젝트 폴더 생성

mkdir my-first-ts
cd my-first-ts

npm 프로젝트 초기화

npm init -y

-y 옵션은 질문 다 스킵하고 기본값으로 생성하는 거예요. package.json 파일이 만들어집니다.

실행 결과:

TypeScript 설정 파일 생성

tsc --init

이 명령어는 tsconfig.json 파일을 만들어줘요. TypeScript 컴파일러의 설정 파일입니다.

실행 결과:

5단계: tsconfig.json 설정

tsconfig.json 파일을 열어보면 주석이 엄청 많아요. 일단 기본 설정만 알아봅시다.

초보자용 추천 설정

tsconfig.json 파일을 이렇게 수정하세요:

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

각 옵션 설명

• target: 어떤 JavaScript 버전으로 변환할지 (ES2020 권장)
• module: 모듈 시스템 (Node.js는 commonjs)
• outDir: 컴파일된 JavaScript 파일을 저장할 폴더
• rootDir: TypeScript 소스 파일이 있는 폴더
• strict: 엄격한 타입 체크 (true 강력 추천!)
• esModuleInterop: import 구문 호환성
• skipLibCheck: 라이브러리 타입 검사 스킵 (컴파일 속도 향상)

6단계: 첫 TypeScript 파일 작성

src 폴더 만들기

mkdir src

hello.ts 파일 만들기

src/hello.ts 파일을 만들고 이렇게 작성:

function greet(name: string): string {
  return `안녕하세요, ${name}님!`;
}

const userName: string = "TypeScript";
const message: string = greet(userName);

console.log(message);

컴파일하기

tsc

이 명령어를 실행하면 dist/hello.js 파일이 생성돼요.

실행 결과:

실행하기

node dist/hello.js

실행 결과:

첫 TypeScript 프로그램 실행 완료!

7단계: Watch 모드 사용하기

매번 tsc 치고 node dist/hello.js 치는 게 귀찮죠? Watch 모드를 쓰면 파일이 바뀔 때마다 자동으로 컴파일해줘요.

tsc --watch

또는 짧게:

tsc -w

실행 결과:

이제 TypeScript 파일을 수정하고 저장만 하면 자동으로 컴파일돼요. 엄청 편합니다!

보너스: ts-node 설치

컴파일 과정 없이 TypeScript를 바로 실행하고 싶다면 ts-node를 쓰면 돼요.

설치

npm install -g ts-node

사용

ts-node src/hello.ts

컴파일 없이 바로 실행돼요. 개발할 때 엄청 편합니다!

실행 결과:

자주 발생하는 문제 해결

1. tsc 명령어를 찾을 수 없음

Windows에서 가끔 이런 에러 나요. 터미널을 껐다 켜보세요. 안 되면 컴퓨터 재시작!

2. 권한 에러 (Mac/Linux)

npm 설치 시 EACCES 에러가 나면 앞에 sudo 붙이세요:

sudo npm install -g typescript

3. TypeScript 버전이 안 맞음

프로젝트마다 다른 버전 쓰고 싶으면 로컬 설치:

npm install --save-dev typescript

그리고 npx tsc 명령어로 실행하면 됩니다.

다음 단계

환경 설정은 끝났어요! 다음 글에서는 TypeScript의 기본 타입들을 배워볼게요. number, string, boolean부터 array, tuple, enum까지 예제와 함께 알려드릴게요.

지금까지 따라오느라 수고하셨어요. 어려웠다면 천천히 다시 해보세요. 한 번 세팅해두면 계속 쓸 수 있으니까요!

---

다음 글 보기

← 블로그 목록으로