본문으로 건너뛰기

안동민 개발노트

본문 시작

개발 환경 설정

Node.js와 패키지 관리 도구, TypeScript 컴파일러, VS Code를 준비하고 tsconfig가 있는 첫 프로젝트를 구성합니다.

타입스크립트 학습에서 의외로 많은 시간이 소모되는 구간이 바로 개발 환경 설정입니다.

명령어는 맞게 입력했는데 컴파일이 안 되거나, 에디터에서는 정상인데 터미널에서만 오류가 나는 상황이 자주 발생하기 때문입니다.

초보 단계에서는 이 문제를 내 코드가 틀렸다로 오해해 불필요한 디버깅에 빠지기 쉽습니다.

이 절은 단순 설치 절차를 나열하는 대신, 왜 이 단계가 필요한지와 어디서 어긋나기 쉬운지를 함께 설명합니다.

특히 전역 설치와 프로젝트 로컬 설치의 차이, 컴파일 설정 파일의 역할을 명확히 이해하면 이후 학습 속도가 훨씬 안정됩니다.

지금 환경을 정확하게 잡아두면, 다음 절부터는 문법 학습과 실습에 집중할 수 있습니다.

TypeScript 환경 설정은 도구의 역할을 분리하는 일이다

Node.js, 패키지 관리자, 컴파일러, 에디터가 각각 맡는 일을 알면 설정 오류를 빠르게 찾을 수 있습니다.

  1. 1
    Node.js

    컴파일된 JavaScript를 실행하고 개발 도구를 돌리는 기반입니다.

  2. 2
    npm

    TypeScript와 관련 패키지를 설치하고 버전을 관리합니다.

  3. 3
    VS Code

    타입 정보를 이용해 오류와 자동 완성을 즉시 보여줍니다.


Node.js와 npm/yarn 설치하기

타입스크립트는 자바스크립트의 상위 집합이며, 결국 자바스크립트로 변환되어 실행됩니다.

따라서 타입스크립트 컴파일러를 설치하고 실행하기 위해서는 Node.js 환경이 필수적입니다.

Node.js는 자바스크립트를 웹 브라우저 밖에서도 실행할 수 있게 해주는 런타임입니다.

Node.js 설치: 가장 먼저 Node.js 공식 웹사이트에 방문하여 여러분의 운영체제에 맞는 설치 파일을 다운로드하고 설치해주세요.

설치 페이지에는 보통 두 가지 버전이 있습니다.

  • LTS (Long Term Support) 버전: 장기적인 안정성을 보장하는 버전입니다. 특별한 이유가 없다면 LTS 버전을 설치하는 것을 권장합니다.
  • Current 버전: 최신 기능을 포함하지만, 안정성이 덜 검증된 버전입니다.

설치 과정은 대부분 다음(Next) 버튼만 누르면 되는 간단한 절차로 이루어져 있습니다.

설치 확인: 설치가 완료되면, 터미널(또는 명령 프롬프트)을 열고 다음 명령어를 입력하여 Node.js와 함께 설치되는 패키지 관리 도구인 npm (Node Package Manager)이 제대로 설치되었는지 확인합니다.

node -v
npm -v

각각 Node.js와 npm의 버전 정보가 출력된다면 성공적으로 설치된 것입니다.

yarn (선택 사항): npm 외에도 yarn이라는 패키지 관리 도구를 사용할 수도 있습니다.

yarn은 npm과 유사한 기능을 제공합니다.

필수는 아니지만, 많은 개발자들이 선호하므로 함께 설치해두는 것도 좋습니다.

npm install -g yarn
yarn -v

-g 옵션은 해당 패키지를 전역(Global)으로 설치한다는 의미입니다.

이렇게 설치하면 어떤 프로젝트 폴더에서든 yarn 명령어를 사용할 수 있습니다.


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

Node.js와 npm(또는 yarn)이 준비되었다면, 이제 타입스크립트 코드를 자바스크립트로 변환해 줄 타입스크립트 컴파일러를 설치할 차례입니다.

이 컴파일러는 tsc라는 명령어로 실행되며, 여러분이 작성한 .ts 파일을 .js 파일로 바꿔주는 역할을 합니다.

터미널에서 다음 명령어를 입력하여 타입스크립트 컴파일러를 전역으로 설치합니다.

npm install -g typescript
# 또는
# yarn global add typescript

설치가 완료되면 다음 명령어로 타입스크립트 컴파일러(tsc)의 버전을 확인해보세요.

tsc -v

버전 정보가 출력된다면 타입스크립트 컴파일러 설치도 성공적으로 완료된 것입니다.

입문 단계에서는 전역 설치가 이해하기 쉽지만, 실무에서는 프로젝트마다 타입스크립트 버전을 고정하기 위해 로컬 설치를 더 많이 사용합니다.

팀 프로젝트에서 버전 차이로 빌드 결과가 달라지는 일을 줄이려면 devDependenciestypescript를 넣고 npx tsc로 실행하는 방식이 안전합니다.

즉 전역 설치는 빠른 학습용, 로컬 설치는 재현 가능한 협업용이라는 기준으로 구분해 두면 혼란이 줄어듭니다.

전역 설치는 학습용, 로컬 설치는 협업용에 가깝다

tsc 명령을 어디서 가져오는지에 따라 팀원마다 같은 버전을 쓰는지 달라집니다.

  1. 1
    전역 설치

    빠르게 시작하기 쉽지만 프로젝트별 버전 고정은 약합니다.

  2. 2
    로컬 설치

    devDependencies에 버전을 고정해 재현성을 높입니다.

  3. 3
    실행 방식

    팀 프로젝트에서는 npx tsc 또는 스크립트 실행이 안전합니다.


코드 에디터 준비하기: VS Code 추천

타입스크립트 개발을 위해 어떤 코드 에디터를 사용해야 할까요?

시중에는 다양한 코드 에디터가 있지만, 타입스크립트 개발에 있어서는 단연 Visual Studio Code (VS Code)를 강력히 추천합니다.

  • 타입스크립트 개발에 최적화: VS Code는 마이크로소프트에서 개발했으며, 타입스크립트와의 궁합이 매우 좋습니다. 별도의 설정 없이도 타입스크립트 코드를 작성할 때 강력한 자동 완성, 오류 검사, 리팩토링 기능을 기본으로 제공합니다.
  • 풍부한 확장 생태계: 다양한 확장(Extension)을 통해 기능을 확장할 수 있으며, 이는 개발 생산성을 크게 향상시킵니다.
  • 경량성과 강력함의 조화: 비교적 가볍게 동작하면서도, 필요한 모든 기능을 제공하는 강력한 에디터입니다.

VS Code 설치: Visual Studio Code 공식 웹사이트에 방문하여 여러분의 운영체제에 맞는 설치 파일을 다운로드하고 설치해주세요.

기본 설정 확인: VS Code를 설치하고 실행하면, 별다른 설정 없이도 .ts 파일을 열면 타입스크립트 구문에 대한 문법 강조(Syntax Highlighting)와 기본적인 타입 검사 기능이 활성화되는 것을 확인할 수 있습니다.


첫 타입스크립트 프로젝트 시작하기

이제 타입스크립트 코드를 작성하고 실행할 개발 환경이 준비되었습니다.

첫 번째 타입스크립트 코드를 작성해보며 환경 설정을 마무리해봅시다.

새 프로젝트 폴더 생성: 원하는 위치에 새로운 폴더를 만들고, VS Code로 해당 폴더를 엽니다.

mkdir my-ts-project
cd my-ts-project
code . # 현재 폴더를 VS Code로 엽니다.

타입스크립트 설정 파일 (tsconfig.json) 생성: 타입스크립트 프로젝트의 루트 폴더에서 다음 명령어를 실행하여 tsconfig.json 파일을 생성합니다.

이 파일은 타입스크립트 컴파일러가 코드를 어떻게 컴파일할지에 대한 설정을 담고 있습니다.

tsc --init

이 명령어를 실행하면 tsconfig.json 파일이 생성되며, 내부에는 다양한 설정들이 주석 처리된 상태로 포함되어 있습니다.

지금은 이 설정들을 자세히 알 필요는 없으며, 기본값으로 두어도 충분합니다.

첫 타입스크립트 파일 작성: my-ts-project 폴더 안에 index.ts라는 파일을 생성하고 다음 코드를 작성해보세요.

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

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

// 의도적으로 오류를 만들어봅시다.
// let age: number = "twenty"; // 오류: 'string' 형식은 'number' 형식에 할당될 수 없습니다.

코드를 저장하면, VS Code가 age 변수에 문자열을 할당하려 할 때 즉시 오류를 표시하는 것을 확인할 수 있습니다.

이것이 바로 타입스크립트의 강력한 타입 검사 기능입니다!

주석 처리된 age 변수 라인은 잠시 오류가 발생하는 것을 확인하기 위한 것이니, 학습 후에는 주석을 유지하거나 제거하셔도 좋습니다.

타입스크립트 코드 컴파일 및 실행: 이제 index.ts 파일을 자바스크립트로 컴파일해봅시다.

터미널에서 다음 명령어를 실행합니다.

tsc

이 명령어를 실행하면 tsconfig.json 파일의 설정에 따라 index.ts 파일이 index.js 파일로 컴파일됩니다.

my-ts-project 폴더 안에 index.js 파일이 새로 생성된 것을 확인해보세요.

index.js (컴파일된 결과)
function greet(name) {
  return `Hello, ${name}! Welcome to TypeScript!`;
}
let userName = "TypeScript Learner";
console.log(greet(userName));
// let age = "twenty"; // 타입스크립트의 타입 정보는 사라지고 자바스크립트로 변환됩니다.

컴파일된 index.js 파일은 순수한 자바스크립트 코드이며, 타입스크립트에서 명시했던 타입 정보들은 사라진 것을 볼 수 있습니다.

타입 정보는 컴파일 시점에만 사용되고 런타임에는 필요 없기 때문입니다.

이제 이 자바스크립트 파일을 Node.js를 이용해 실행해봅시다.

node index.js

터미널에 Hello, TypeScript Learner! Welcome to TypeScript! 메시지가 출력된다면 설정이 정상적으로 완료된 것입니다.

아래 다이어그램은 첫 프로젝트에서 자주 헷갈리는 tsconfig.json의 역할을 파일 범위, 검사 강도, 변환 결과 기준으로 정리한 것입니다.

tsconfig.json은 TypeScript 프로젝트의 검사 규칙이다

어떤 파일을 검사하고 얼마나 엄격하게 볼지, 결과를 어디로 낼지를 한곳에서 정합니다.

  1. 1
    파일 범위

    include, exclude로 검사 대상을 정합니다.

  2. 2
    검사 강도

    strict 같은 옵션으로 타입 안전성의 기준을 정합니다.

  3. 3
    출력 결과

    target, module, outDir로 JavaScript 생성 방식을 정합니다.

이제 타입스크립트 개발 환경을 준비했습니다.

다음 절부터는 기본 타입, 함수, 객체 타입, 컴파일 흐름을 순서대로 다룹니다.

설정의 끝은 .ts 작성, 검사, 실행이 이어지는 상태다

설치 자체보다 중요한 것은 작성한 파일이 타입 검사와 JavaScript 실행으로 자연스럽게 연결되는지입니다.

  1. 1
    작성

    프로젝트 안에 .ts 파일을 만들고 타입을 붙입니다.

  2. 2
    컴파일

    tsc가 설정을 읽어 .js 결과를 만듭니다.

  3. 3
    실행

    Node.js 또는 브라우저가 변환된 JavaScript를 실행합니다.

아래 다이어그램은 설치, 로컬 컴파일러, tsconfig.json, 에디터 피드백을 하나의 환경 점검 순서로 묶어 보여줍니다.

환경 점검은 설치보다 실행 흐름 확인이 우선이다

문제가 생기면 Node, 패키지, tsconfig, 에디터 피드백 순서로 확인하면 원인을 좁히기 쉽습니다.

  1. 1
    버전 확인

    node, npm, tsc가 예상한 위치에서 실행되는지 봅니다.

  2. 2
    설정 확인

    tsconfig.json이 프로젝트 루트에 있고 대상 파일을 포함하는지 확인합니다.

  3. 3
    피드백 확인

    에디터 오류와 터미널 컴파일 결과가 같은 방향인지 봅니다.

아래 다이어그램은 첫 프로젝트 환경을 다시 만들 때 빠뜨리기 쉬운 실행 기준을 체크리스트로 묶습니다.

첫 프로젝트는 네 가지 실행 기준만 확인하면 된다

설치가 복잡해 보여도 처음에는 파일 생성부터 실행 결과까지 이어지는지만 보면 충분합니다.

  1. 프로젝트

    폴더를 만들고 패키지와 설정 파일을 준비합니다.

  2. 소스

    index.ts 같은 첫 파일을 작성합니다.

  3. 결과

    tsc 후 생성된 JavaScript를 node로 실행합니다.

환경 설정 뒤에는 타입 경계와 호출부 영향을 본다

도구가 준비되면 이제 어떤 타입 변경이 어디까지 영향을 주는지 관찰할 수 있습니다.

  1. 1
    타입 경계

    외부 입력, 함수 인자, 반환값을 먼저 봅니다.

  2. 2
    추론 범위

    직접 쓰지 않아도 TypeScript가 알아내는 타입을 확인합니다.

  3. 3
    호출부 영향

    선언을 바꿨을 때 에디터가 어느 사용처를 알려주는지 봅니다.

아래 다이어그램은 TypeScript 개발 환경을 다시 만들 때 빠뜨리기 쉬운 설치와 실행 기준을 정리합니다.

TypeScript 환경은 설치, 설정, 실행 확인으로 완성된다

Node와 npm이 기반을 만들고, TypeScript와 tsconfig가 검사 흐름을 정합니다.

  1. 1
    설치

    Node.js와 패키지 관리 도구를 준비합니다.

  2. 2
    설정

    tsconfig.json으로 프로젝트 규칙을 만듭니다.

  3. 3
    확인

    tsc와 node 실행으로 결과를 검증합니다.