“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 명령어로 실행하면 됩니다.

운영자 실전 노트

실제 프로젝트 진행하며 겪은 문제

• tsconfig.json 옵션이 너무 많아서 어떤 걸 켜야 할지 혼란 → 처음엔 기본 설정으로 시작 후 필요에 따라 점진적 추가
• strict 모드를 나중에 켜려니 기존 코드 에러 폭발 → 처음부터 strict: true로 시작하는 게 훨씬 편함

이 경험을 통해 알게 된 점

• strict 모드는 처음부터 켜고 시작하는 게 정신 건강에 좋다
• tsconfig.json은 프로젝트 성격에 맞춰 점진적으로 조정하면 된다

다음 글에서는 TypeScript의 기본 타입들을 배운다. number, string, boolean부터 array, tuple, enum까지 예제와 함께 다룰 예정이다.

---

다음 글 보기

← 블로그 목록으로