본문 바로가기
스터디 열기

타입스크립트 환경설정

1. 환경설정

타입스크립트를 배우는 목적이 다양하기 때문에 다양한 환경을 소개합니다. 가장 편한 환경에서 시작해보세요.

타입스크립트 개발 환경은 크게 세 가지로 나눌 수 있습니다.

  1. 온라인 플레이그라운드: 설치 없이 바로 사용 가능
  2. 로컬 Node.js 환경: 실제 개발에 가까운 환경
  3. IDE 통합 환경: 본격적인 프로젝트 개발 환경

각각의 장단점을 살펴보고 자신에게 맞는 환경을 선택해보세요. 이 교재의 실행 블록은 교재 화면에서 [실행]을 눌러 타입 검사 결과와 실행 결과를 바로 볼 수 있습니다.

1.1 위니브 타입스크립트

위니브에서 서비스하고 있는 '위니브 타입스크립트'에서 설치 없이 사용해 볼 수 있습니다.

위니브 타입스크립트

1.1.1 주요 기능

  • 설치 불필요: 브라우저에서 바로 실행 가능
  • 폰트 크기 조절: 오른쪽 상단 +와 - 버튼으로 editor와 console의 폰트 크기 조절
  • 실행 단축키: Ctrl + Enter로 코드 실행
  • 테마 변경: 우측상단 토글로 화이트모드와 다크모드 선택
  • 코드 스니펫: log, for, if, async 등 간단한 단축키 제공

1.1.2 사용법

  1. 사이트에 접속하면 간단한 샘플 코드가 작성되어 있습니다.
  2. Ctrl + Enter를 눌러서 실행해보겠습니다.
타입스크립트 플레이그라운드 실행 결과

1.1.3 활용 예시

// 간단한 타입스크립트 코드 테스트
function greet(name: string): string {
  return `안녕하세요, ${name}님!`;
}

console.log(greet("타입스크립트"));
console.log(greet(123)); // 오류: 숫자는 string 타입이 아님

이 교재의 실행 블록에서도 바로 확인할 수 있습니다. [실행]을 누르면 타입 검사 결과에 error TS2345: 'number' 형식의 인수는 'string' 형식의 매개 변수에 할당될 수 없습니다.가 7번째 줄에 표시되고, 실행 결과에는 안녕하세요, 타입스크립트님!과 안녕하세요, 123님!이 모두 찍힙니다. 타입 오류는 알려 주지만 코드는 자바스크립트로 바뀌어 그대로 실행되기 때문입니다.

해당 도구는 설치 없이 간편하게 테스트 해보는 용도로 사용하기 적합한 도구입니다.

1.2 타입스크립트 플레이그라운드

타입스크립트 공식 홈페이지에서 제공하는 플레이그라운드입니다. 아래 링크를 통해 접속할 수 있습니다.

타입스크립트 플레이그라운드

1.2.1 공식 플레이그라운드의 장점

  1. 최신 기능: 최신 타입스크립트 기능을 사용할 수 있습니다.
  2. 컴파일 옵션: 다양한 컴파일러 옵션을 설정할 수 있습니다.
  3. 예제 코드: 다양한 예제 코드를 제공합니다. Example 탭에서 다양한 예제를 확인할 수 있습니다.
  4. JavaScript 변환: 타입스크립트 코드가 어떻게 JavaScript로 변환되는지 실시간으로 확인 가능합니다. 오른쪽 탭에 .JS 탭을 클릭하면 변환된 JavaScript 코드를 볼 수 있습니다.

1.2.2 사용 팁

아래 코드를 입력하고 오른쪽에서 .JS 탭을 클릭해 변환된 JavaScript 코드를 확인해보세요.

const num: number[] = [1, 2, 3];

아래 코드를 실행하고 변환된 JavaScript 코드를 확인해보세요.

// 타입스크립트 플레이그라운드에서 테스트해보기
interface User {
  name: string;
  age: number;
  email?: string; // 선택적 속성
}

function createUser(userData: User): User {
  return {
    name: userData.name,
    age: userData.age,
    email: userData.email || "이메일 없음"
  };
}

const user = createUser({
  name: "김타입",
  age: 25
});

console.log(user);

이처럼 다양한 코드를 실험해보고 타입스크립트가 어떻게 동작하는지 이해하는 데 도움이 됩니다.

1.3 Node 환경 세팅

실제 개발 환경에서는 로컬에서 타입스크립트를 실행할 수 있어야 합니다. Node.js를 설치하고, 타입스크립트를 설치하여 로컬 환경에서 작성할 수 있습니다.

console.log("hello world");

이렇게 저장하고 node 001.ts로 실행하면 hello world가 출력되지만 이는 TypeScript가 아닌 JavaScript 코드로 해당 코드를 실행시킨 것입니다. 그래서 반드시 tsx와 같은 것을 사용해야 합니다.

2026년의 Node.js는 .ts 파일을 바로 실행합니다

위 설명은 예전 Node.js 기준입니다. Node.js는 v22.18.0·v23.6.0부터 '타입 지우기(type stripping)'를 기본으로 켜서, node hello.ts처럼 타입이 들어간 파일도 바로 실행합니다. v24.12.0·v25.2.0에서는 이 기능이 안정(stable) 단계가 되었습니다(Node.js 공식 문서). 2026-11-07에 Node.js 24.22.1로 아래 hello.ts를 node hello.ts로 실행해 안녕하세요, 타입스크립트님!이 출력되는 것을 확인했습니다.

다만 두 가지를 알아 두세요.

  1. 타입 검사는 하지 않습니다. 타입만 지우고 실행하므로 greet(123) 같은 타입 오류가 있어도 그대로 실행됩니다. 타입 검사는 tsc --noEmit이나 편집기가 맡습니다.
  2. 일부 문법은 실행되지 않습니다. enum, 실행 코드가 있는 namespace처럼 '지우기만으로는 자바스크립트가 되지 않는' 문법을 만나면 ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX 오류로 멈춥니다(Node.js 24.22.1에서 enum 파일로 확인). tsconfig.json도 읽지 않습니다.

이 교재는 수업 환경을 맞추기 위해 아래의 tsx·ts-node·tsc 방법을 함께 소개합니다.

먼저 Node.js가 설치되어 있어야 합니다. 아래 명령어로 확인해보세요.

node --version
npm --version

1.3.1 tsx 사용하기

tsx는 타입스크립트를 바로 실행할 수 있는 가장 손쉬운 방법입니다. 다만 tsx는 타입 검사를 하지 않으므로 타입 오류가 있어도 실행이 되기 때문에 주의가 필요합니다. (2026-11-07에 tsx 4.23.15로 greet(123)처럼 타입이 틀린 코드를 실행해 보면 오류 없이 결과가 출력됩니다.)

# tsx와 typescript 전역 설치
npm install -g tsx typescript

설치를 다하면 아래 명령어로 설치를 확인할 수 있습니다.

npm list -g

맥북은 sudo를 붙여 실행해야 할 수 있습니다. 지금 터미널에서 입력한 명령어는 아래 모듈 설치할 때에도 동일하게 적용됩니다.

hello.ts 파일을 생성하고 아래 코드를 작성합니다.

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

const message = greet("타입스크립트");
console.log(message);

// 타입 오류 예시 (주석 해제하면 오류 발생)
// console.log(greet(123));

아래 명령어로 실행할 수 있습니다.

tsx hello.ts

Windows의 경우 보안 옵션 때문에 tsx 명령어가 작동하지 않을 수 있습니다. 이 경우 파워쉘을 관리자 권한으로 실행하여 아래 명령어로 실행해보세요.

Set-ExecutionPolicy RemoteSigned

[A]모두 예를 선택하고 다시 실행해보세요.

1.3.2 ts-node 사용하기

ts-node는 더 많은 옵션을 제공하며 실무에서 많이 사용됩니다. 수업은 ts-node를 기준으로 진행합니다.

# ts-node와 typescript 전역 설치 (typescript는 6 버전으로 고정)
npm install -g ts-node typescript@6

ts-node를 쓸 때는 TypeScript 6을 함께 설치하세요

이전 판에서는 npm install -g ts-node typescript로 안내했습니다. 그런데 2026년 7월 8일 나온 TypeScript 7부터 npm install typescript가 7 버전을 설치하고, 7 버전은 다른 도구가 불러 쓰는 자바스크립트 API를 아직 제공하지 않습니다. ts-node는 2023년 12월(10.9.2) 이후 새 버전이 나오지 않아 이 변화에 맞춰지지 않았습니다. 2026-11-07에 ts-node 10.9.2 + TypeScript 7.0.2로 ts-node hello.ts를 실행하면 TypeError: Cannot read properties of undefined (reading 'fileExists')로 멈추고, TypeScript 6.0.3이나 5.9.3과 함께 설치하면 정상으로 실행됩니다. 그래서 위 명령에서 typescript@6으로 버전을 고정했습니다. 새로 시작한다면 tsx나 Node.js의 .ts 직접 실행(위 상자)을 먼저 써 보는 것도 좋습니다.

tsconfig.json 파일을 생성해야 합니다.

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2020",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true
  },
  "ts-node": {
    "esm": false
  }
}

같은 hello.ts 파일을 아래 명령어로 실행할 수 있습니다.

ts-node hello.ts

1.3.3 컴파일 후 실행하기

타입스크립트를 JavaScript로 컴파일한 후 실행하는 방법도 있습니다.

# 타입스크립트 파일을 JavaScript로 컴파일
tsc hello.ts

# 생성된 JavaScript 파일 실행
node hello.js

tsconfig.json이 있는 폴더에서는 tsc hello.ts가 거절됩니다

TypeScript 6.0부터는 tsconfig.json이 있는 폴더에서 tsc hello.ts처럼 파일 이름을 주면 컴파일하지 않고 아래 오류를 냅니다. 바로 위 1.3.2에서 tsconfig.json을 만들었다면 이 경우에 해당합니다.

error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error.

이때는 둘 중 하나를 고릅니다.

# 1) tsconfig.json 설정대로 폴더 전체를 컴파일 (파일 이름을 주지 않음)
tsc
node hello.js

# 2) tsconfig.json을 무시하고 이 파일만 컴파일
tsc --ignoreConfig hello.ts
node hello.js

2026-11-07에 TypeScript 6.0.3과 7.0.2에서 같은 오류와 두 해결 방법을 확인했습니다. tsconfig.json이 없는 폴더라면 tsc hello.ts가 이전처럼 동작합니다.

1.3.4 환경별 비교

방법장점단점사용 시점
tsx간단하고 빠름제한적인 설정학습, 간단한 스크립트
ts-node많은 옵션 제공설정 파일 필요실무 개발
tsc + node명확한 컴파일 과정두 단계 필요프로덕션 빌드
node (v22.18 이상)설치 없이 node 파일.ts타입 검사 안 함, enum 등 일부 문법 불가간단한 스크립트

표에서 tsx와 node 직접 실행은 타입 검사를 하지 않습니다. 어떤 방법으로 실행하든 타입 오류는 편집기나 tsc --noEmit으로 따로 확인합니다.

1.4 React에서 타입스크립트는 어떻게 동작하고 관리되나요?

브라우저는 TypeScript를 직접 실행할 수 없습니다. 따라서 React + TypeScript 프로젝트는 반드시 JavaScript로 변환하는 과정(컴파일)을 거쳐야 합니다.

1.4.1 빌드 과정

TypeScript + JSX (.tsx 파일)
         ↓
    빌드 도구가 변환
         ↓
   JavaScript (.js 파일)
         ↓
   브라우저에서 실행

즉, React 라이브러리는 UI 컴포넌트를 만드는 기능만 제공하고 빌드 기능은 포함하지 않습니다. 빌드는 Vite, Webpack과 같은 빌드 엔진이 담당합니다.

1.4.2 빌드 도구 (별도 설치 필요)

  • Vite: 빠른 개발 서버와 최적화된 빌드 제공
  • Webpack: 강력하고 유연한 번들러(일반적으로 create react app 명령어로 React 프로젝트 생성시 Webpack + Babel 조합)

Create React App은 React 팀이 2025년 2월 14일에 새 프로젝트에는 쓰지 말라고 공지했습니다(Sunsetting Create React App). 지금 React + TypeScript 프로젝트를 새로 만든다면 npm create vite@latest my-app -- --template react-ts처럼 Vite의 TypeScript 템플릿을 쓰는 것이 일반적입니다.

마지막 수정