개발 환경 준비 완료! 첫 번째 TypeScript 프로그램
30분 안에 여기까지 갑니다
첫 챕터에서 TypeScript가 왜 필요한지 살펴봤다면, 이제는 책상에 공구를 꺼낼 차례다. 이번 챕터의 목표는 거창하지 않다. 내 컴퓨터에서 TypeScript 파일을 만들고, 자바스크립트로 컴파일하고, 실제로 실행해 보는 것. 이 세 가지만 해내면 TypeScript는 더 이상 "언젠가 배워야 할 것"이 아니라 "이미 한 번 써 본 것"이 된다.
오늘 만들 프로젝트는 아주 작다. 하지만 작아서 좋다. 작은 프로그램이야말로 환경이 제대로 준비되었는지 가장 빨리 알려 주는 정직한 친구이기 때문이다.
먼저 준비할 것
TypeScript는 혼자서 실행되지 않는다. TypeScript 코드는 먼저 자바스크립트로 바뀐 다음 실행된다. 그래서 Node.js와 npm이 필요하다. 편집기는 VS Code를 가장 많이 쓰지만, 어떤 편집기를 써도 괜찮다. 다만 VS Code는 TypeScript 문법 지원을 기본 제공하되, tsc 컴파일러는 따로 설치해야 한다.1
터미널에서 먼저 아래 명령으로 준비 상태를 확인해 보자.
node -v
npm -v버전 번호가 보이면 출발 준비 완료다. 만약 둘 중 하나라도 나오지 않으면 Node.js LTS 버전을 먼저 설치하자.
프로젝트 폴더 만들기
처음부터 파일이 뒤섞이면 금방 어지러워진다. 작은 프로젝트라도 폴더 구조를 가볍게 잡아 두는 습관이 좋다.
mkdir my-first-typescript
cd my-first-typescript
npm init -ynpm init -y는 package.json을 만들어 준다. 이 파일은 "이 프로젝트는 이름이 뭐고, 어떤 패키지를 쓰고, 어떤 명령으로 실행하는가?"를 기록하는 명함 같은 존재다.
이제 TypeScript를 프로젝트 안에 설치하자.
npm install -D typescript @types/node여기서 -D는 개발할 때만 필요한 도구라는 뜻이다. 프로그램을 배포할 때 꼭 따라갈 필요는 없다는 의미라고 생각하면 된다.
설치가 잘 되었는지 확인하려면 다음 명령을 실행한다.
npx tsc -vnpx는 "이 프로젝트에 설치된 패키지를 실행해 줘"라고 말하는 방법이다. 초보자에게는 이 방식이 특히 좋다. 팀 프로젝트에서도 버전이 덜 헷갈리기 때문이다.
TypeScript 설정 파일 만들기
이제 TypeScript에게 "우리 프로젝트에서 어떻게 일하면 되는지" 알려 줄 차례다.
npx tsc --init그러면 루트 폴더에 tsconfig.json이 생긴다. 이 파일이 있으면 현재 폴더가 TypeScript 프로젝트의 기준점이 되고, tsc는 이 설정을 읽어 전체 프로젝트를 컴파일한다.2
처음에는 설정 파일이 길고 무섭게 보일 수 있다. 실제로 tsc --init이 만들어 주는 기본 내용은 TypeScript 버전에 따라 조금씩 달라질 수 있다. 그래서 초반에는 "자동으로 만들어진 파일을 그대로 외우기"보다, 대표적인 설정이 무슨 뜻인지 이해하는 것이 훨씬 중요하다.
예를 들어 아래 같은 설정은 초보자가 흐름을 이해하기에 좋은 대표 예시다.
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"rootDir": "./src",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true,
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}이 설정을 사람 말로 번역하면 이렇다.
src폴더의 TypeScript 파일을 읽는다.자바스크립트로 바꾼 결과는
dist폴더에 둔다.비교적 현대적인 자바스크립트 문법을 목표로 한다.
모듈 방식은 여기서는 이해하기 쉬운
CommonJS를 예시로 쓴다.strict로 엄격한 타입 검사를 켠다.3sourceMap으로 디버깅을 편하게 만든다.4
특히 strict는 꼭 기억해 두자. TypeScript를 쓰는 가장 큰 이유 중 하나가 "실수를 빨리 잡는 것"인데, 이 옵션이 그 역할을 진지하게 해 준다. 초보자일수록 느슨한 설정보다 명확한 피드백이 더 도움이 된다.
첫 번째 TypeScript 파일 작성하기
이제 진짜로 코드를 써 보자.
먼저 폴더를 만든다.
mkdir src그리고 src/index.ts 파일을 만든 뒤 다음 코드를 넣어 보자.
function greet(name: string): string {
return `안녕하세요, ${name}! 드디어 TypeScript를 실행했군요.`;
}
const userName: string = "초보 개발자";
console.log(greet(userName));이 코드는 아주 단순하지만 중요한 포인트가 들어 있다.
name: string은 이 함수가 문자열만 받겠다고 약속하는 문장이다. : string이 함수 뒤에 한 번 더 붙어 있는 이유는 반환값도 문자열이라고 알려 주기 위해서다. 즉, "문자열을 받아 문자열을 돌려주는 함수"라는 뜻이다.
이제 만약 아래처럼 숫자를 넣으면 어떨까?
console.log(greet(123));자바스크립트였다면 일단 실행은 되고, 나중에 다른 곳에서 이상한 상황을 만들 수도 있다. 하지만 TypeScript는 "잠깐, 이 함수는 문자열만 받기로 했잖아?" 하고 먼저 잡아 준다. 이 순간이 바로 TypeScript가 낯설지만 든든하게 느껴지는 첫 장면이다.
컴파일하기: TypeScript를 JavaScript로 바꾸기
이제 터미널에서 아래 명령을 실행해 보자.
npx tsc여기서 중요한 점이 하나 있다. tsconfig.json을 기준으로 프로젝트 전체를 컴파일하려면 파일 이름을 직접 붙이지 말고 npx tsc처럼 실행하는 편이 좋다. TypeScript 공식 문서도 명령줄에 입력 파일을 직접 지정하면 tsconfig.json은 무시된다고 설명한다.2
즉, 아래 둘은 느낌이 다르다.
npx tsc이건 프로젝트 설정을 읽는다.
npx tsc src/index.ts이건 파일 하나를 기본 설정으로 컴파일하는 쪽에 가깝다.
컴파일이 끝나면 dist/index.js 파일이 생긴다. 즉, 우리가 쓴 src/index.ts가 실행 가능한 자바스크립트로 바뀐 것이다.
실행하기: 드디어 내 코드가 움직인다
이제 Node.js로 실행해 보자.
node dist/index.js정상이라면 이런 출력이 보일 것이다.
안녕하세요, 초보 개발자! 드디어 TypeScript를 실행했군요.축하한다. 지금 방금, 당신은 TypeScript 파일을 만들고, 컴파일하고, 실행했다. 이제 TypeScript는 더 이상 소개 글 속 개념이 아니라 손으로 만져 본 도구다.
한 번에 정리하는 전체 흐름
처음에는 명령이 많아 보여도 실제 흐름은 아주 단순하다.
mkdir my-first-typescript
cd my-first-typescript
npm init -y
npm install -D typescript @types/node
npx tsc --init
mkdir src그다음 src/index.ts를 작성하고,
npx tsc
node dist/index.js이 순서로 가면 된다. 딱 이 패턴만 익혀도 이후 챕터를 따라가는 데 큰 문제가 없다.
매번 치기 귀찮다면: npm scripts 추가하기
터미널 명령을 줄이고 싶다면 package.json에 스크립트를 추가하자.
{
"scripts": {
"build": "tsc",
"start": "node dist/index.js",
"dev": "tsc --watch"
}
}이제 다음처럼 더 짧게 실행할 수 있다.
npm run build
npm run startnpm run dev는 파일을 저장할 때마다 자동으로 다시 컴파일한다. 코드를 자주 고치는 초반 학습 단계에서 특히 편하다. "수정 → 저장 → 자동 컴파일" 흐름이 만들어지면 손이 훨씬 가벼워진다.
tsconfig.json, 딱 이것만은 알고 가자
처음 배우는 사람에게 tsconfig.json은 비밀 메뉴판처럼 보인다. 하지만 자주 만나는 옵션은 생각보다 적다.
target
어느 수준의 자바스크립트 문법으로 변환할지 정한다. 예를 들어 ES2020이면 비교적 최신 문법을 활용하는 쪽이다. 너무 낮게 잡으면 최신 문법이 많이 바뀌어 출력될 수 있고, 너무 높게 잡으면 실행 환경이 따라오지 못할 수 있다.
module
파일을 서로 불러오는 방식이다. 이 장에서는 흐름 설명을 위해 CommonJS를 예시로 썼다. 나중에 번들러나 프레임워크를 쓰면 ESNext 같은 설정도 자주 만나게 된다.
rootDir
내 TypeScript 원본 파일이 어디에 있는지 알려 준다. 보통 src를 많이 쓴다.
outDir
컴파일 결과인 자바스크립트를 어디에 둘지 정한다. dist를 자주 쓴다. 원본과 결과물이 섞이지 않아 훨씬 깔끔하다.
strict
엄격 모드다. TypeScript의 잔소리 모드라고 생각해도 된다. 그런데 이 잔소리가 꽤 유능하다. 초반에는 오류가 많아 보여도, 나중에는 "아, 이래서 켜 두라고 했구나"라는 순간이 온다.
sourceMap
디버깅할 때 실행 중인 자바스크립트와 원본 TypeScript를 연결해 준다.4 나중에 VS Code 디버깅을 할 때 특히 유용하다.
자주 만나는 실수와 해결법
처음 환경 설정에서는 코드 실력보다 경로와 명령어가 더 큰 적이 되곤 한다. 아래 문제들은 아주 흔하다.
tsc를 찾을 수 없다고 나올 때
전역 설치를 하지 않았더라도 너무 당황하지 말자. 프로젝트 안에 TypeScript를 설치했다면 npx tsc로 실행하면 된다.
dist/index.js가 없다고 나올 때
대개 컴파일이 실패했거나, outDir 설정이 없어서 다른 위치에 생성된 경우다. 먼저 npx tsc 실행 결과에 오류가 없는지 확인하자.
tsconfig.json을 바꿨는데 반영되지 않을 때
npx tsc src/index.ts처럼 파일명을 직접 준 경우일 수 있다. 프로젝트 설정을 쓰려면 npx tsc만 실행하자.2
오류 메시지가 너무 무서울 때
좋은 소식이 있다. 대부분의 오류 메시지는 "무엇이 문제인지"를 꽤 친절하게 말해 준다. 처음에는 영어 문장이 길어 보여도 핵심만 보면 된다. 주로 string, number, not assignable 같은 단어가 힌트다.
VS Code를 쓴다면 더 편한 이유
VS Code에서는 TypeScript를 쓸 때 꽤 많은 도움을 받는다. 자동 완성, 빨간 밑줄, 빠른 수정 제안, 타입 정보 미리보기 등이 대표적이다.1 다시 말해, TypeScript는 언어 자체도 좋지만 도구와 함께 쓸 때 진가가 더 잘 드러난다.
타이핑을 하다가 에러가 바로 보이는 경험은 초보자에게 특히 유익하다. "실행하기 전에 틀린 부분을 알 수 있다"는 감각이 붙기 시작하면 디버깅 스트레스가 눈에 띄게 줄어든다.
이 챕터의 작은 결론
이번 챕터에서 우리가 한 일은 사실 꽤 많다. 하지만 흐름은 단순했다. 프로젝트를 만들고, TypeScript를 설치하고, tsconfig.json을 만들고, 첫 .ts 파일을 작성한 뒤, 컴파일하고 실행했다.
이제 다음 챕터에서 타입을 본격적으로 배울 준비가 되었다. 중요한 건 완벽하게 외우는 것이 아니다. "TypeScript 프로젝트는 이렇게 시작하는구나"라는 감각을 손에 넣는 것이다.
오늘의 성과를 한 문장으로 요약하면 이렇다.
TypeScript는 설치만 끝나면 생각보다 금방 친해진다. 그리고 첫 실행이 끝나는 순간, 낯섦은 절반 이하로 줄어든다.
참고
1TypeScript tutorial in Visual Studio Code
2TypeScript: Documentation - tsc CLI Options
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.