실행 가능한 TypeScript 문서: TypeScript 설치

Q: TypeScript는 어떻게 설치하나요?

Node.js를 설치한 다음 프로젝트 폴더에서 npm install --save-dev typescript를 실행합니다. 그러면 컴파일러가 node_modules와 package.json의 devDependencies에 추가됩니다. 실행은 npx tsc로 합니다. 컴퓨터 전체에서 쓰는 tsc 명령이 필요하면 대신 npm install -g typescript를 쓰세요.

Q: 설치된 TypeScript 버전은 어떻게 확인하나요?

프로젝트 폴더에서 npx tsc --version(또는 npx tsc -v)을 실행합니다. Version 7.0.2 같은 결과가 출력됩니다. npx 없이 tsc --version을 실행하면 전역 설치가 있을 경우 그 버전을 알려 주고, npm ls typescript는 프로젝트 의존성이 실제로 설치한 버전을 보여 줍니다.

Q: 새 TypeScript 프로젝트는 어떻게 시작하나요?

npm init -y, npm install --save-dev typescript, npx tsc --init을 차례로 실행합니다. 마지막 명령은 권장 설정이 담긴 tsconfig.json을 씁니다. 코드는 src에 두고 rootDir을 ./src로, outDir을 ./dist로 설정한 뒤, npx tsc로 컴파일하고 node dist/index.js로 결과를 실행합니다.

Q: TypeScript는 전역으로 설치해야 하나요, 로컬로 설치해야 하나요?

로컬에, 개발 의존성으로 설치하세요. 그러면 프로젝트마다 package.json에 자신의 컴파일러 버전을 고정하고, 팀원과 CI는 npm install로 같은 버전을 받습니다. 전역 설치는 빠른 실험에 편리하지만 프로젝트가 기대하는 버전과 다를 수 있습니다.

Q: npx tsc가 "This is not the tsc command you are looking for"라고 하는 이유는 무엇인가요?

그 폴더에 TypeScript가 설치되어 있지 않아서 npx가 tsc라는 이름의 관련 없는 폐기된 npm 패키지를 내려받았기 때문입니다. 이 패키지는 그 경고만 출력합니다. 컴파일러의 패키지 이름은 typescript입니다. 먼저 npm install --save-dev typescript를 실행하면 npx tsc가 올바른 명령을 찾습니다.

TypeScript는 typescript라는 이름의 npm 패키지입니다. 프로젝트에 설치하고 동작하는지 확인해 보세요.

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

이 패키지는 TypeScript 컴파일러인 tsc 명령을 제공합니다. 설치하려면 Node.js와 npm(Node.js에 포함되어 있음)이 필요합니다. Node.js는 nodejs.org나 시스템의 패키지 관리자에서 받고, node --version으로 확인하세요.

TypeScript를 써 보기만 할 거라면 아무것도 설치할 필요가 없습니다. 이 블록은 브라우저에서 컴파일되고 실행됩니다.

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

프로젝트에 TypeScript 설치하기

권장하는 방법은 프로젝트의 개발 의존성으로 로컬에 설치하는 것입니다.

mkdir hello-ts
cd hello-ts
npm init -y
npm install --save-dev typescript

npm install --save-dev typescript(줄여서 npm i -D typescript)는 컴파일러를 node_modules에 넣고 package.json에 기록합니다.

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

코드를 실행하는 데가 아니라 빌드하는 데만 필요하므로 개발 의존성입니다. 프로젝트를 복제해서 npm install을 실행하는 사람은 누구나 같은 컴파일러 버전을 받습니다.

로컬 컴파일러를 실행하려면 앞에 npx를 붙이세요. npx는 node_modules/.bin에서 명령을 찾습니다.

npx tsc --version

package.json의 스크립트 안에서는 npx 없이 tsc라고 써도 됩니다. npm이 스크립트 실행 시 node_modules/.bin을 PATH에 추가하기 때문입니다.

{
    "scripts": {
        "build": "tsc",
        "typecheck": "tsc --noEmit"
    }
}

그러면 npm run build는 컴파일하고, npm run typecheck는 파일을 쓰지 않고 타입만 검사합니다.

TypeScript 버전 확인

명령	알려 주는 것
`npx tsc --version` 또는 `npx tsc -v`	프로젝트가 쓰는 컴파일러(로컬 설치 우선)
`tsc --version`	전역 설치(있는 경우)
`npm ls typescript`	프로젝트에 설치된 버전과 그것에 의존하는 패키지
`npm view typescript version`	npm에 공개된 최신 안정 버전

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

npx tsc --version과 tsc --version이 서로 다른 버전을 출력한다면, 프로젝트에 자체 컴파일러가 있고 전역 컴파일러는 그보다 오래되었거나 최신입니다. 빌드에 중요한 것은 프로젝트의 버전입니다.

TypeScript 전역 설치

전역으로 설치하면 npx 없이 모든 터미널에서 tsc 명령을 쓸 수 있습니다.

npm install -g typescript
tsc --version

macOS와 Linux에서 Node.js를 시스템 전체에 설치했다면 EACCES 권한 오류로 실패할 수 있습니다. nvm이나 fnm 같은 버전 관리자로 Node.js를 설치하면 이 문제를 피할 수 있고, sudo npm install -g는 권장하지 않습니다.

전역 명령은 빠른 실험에 쓰세요. 실제 프로젝트라면 로컬 설치도 함께 두세요. 그러면 package.json에 버전이 기록되고, 전역 컴파일러를 업데이트해도 프로젝트의 빌드 방식이 바뀌지 않습니다.

pnpm, Yarn, Bun으로 설치하기

어떤 JavaScript 패키지 관리자든 같은 패키지를 설치합니다.

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

컴파일러는 pnpm tsc, yarn tsc, bunx tsc로 실행합니다.

tsc --init으로 tsconfig.json 만들기

tsconfig.json 파일은 폴더를 TypeScript 프로젝트로 표시하고 컴파일러 옵션을 담습니다. 하나 생성해 보세요.

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

생성된 파일(TypeScript 7)은 strict와 몇 가지 검사를 더 켜고, "module": "nodenext"와 "target": "esnext"를 쓰며, rootDir과 outDir은 주석 처리된 줄로 들어 있습니다. 컴파일러가 src에서 읽고 dist에 쓰도록 이 두 줄의 주석을 푸세요.

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

위는 줄인 모습이고, 실제 파일에는 각각 주석이 달린 옵션이 더 있습니다. 각 옵션이 하는 일은 tsconfig 페이지에서 설명합니다. 같은 폴더에서 npx tsc --init을 다시 실행하면 error TS5054: A 'tsconfig.json' file is already defined로 실패하므로 설정을 덮어쓰는 일은 없습니다.

첫 파일 컴파일하기

src/index.ts를 만듭니다.

function greet(name: string): string {
    return `Hello, ${name}!`;
}

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

그런 다음 컴파일하고 실행합니다.

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

인수 없이 npx tsc를 실행하면 tsconfig.json을 읽고, 포함된 모든 파일을 타입 검사하고, 출력을 dist에 씁니다. 생성된 설정에서는 파일마다 index.js와 함께 index.d.ts(타입 선언)와 .map 파일(소스 맵)이 생깁니다.

출력에 대해 알아 둘 점 두 가지:

기본적으로 타입 오류가 있어도 출력은 멈추지 않습니다. tsc는 오류를 보고하고 0이 아닌 코드로 종료하지만 JavaScript는 그대로 씁니다. 오류가 있는 동안 아무것도 쓰지 않으려면 "noEmitOnError": true를 설정하세요.
tsconfig.json이 있으면 파일 이름을 넘기지 마세요. npx tsc src/index.ts는 error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline.으로 실패합니다. 그냥 npx tsc를 실행하거나, 정말로 파일 하나를 기본 설정으로 컴파일하고 싶다면 --ignoreConfig를 더하세요.

감시 모드

--watch(줄여서 -w)는 컴파일러를 계속 실행하면서 파일이 바뀔 때마다 다시 컴파일합니다.

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

에디터 옆의 터미널에 열어 두세요. 멈추려면 Ctrl+C를 누릅니다.

특정 TypeScript 버전 설치하기

@ 뒤에 버전을 붙입니다.

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

TypeScript 6은 컴파일러가 JavaScript로 작성된 마지막 버전입니다. 컴파일러의 JavaScript API를 호출하는 일부 도구는 아직 이 버전이 필요하며, 업그레이드 방법과 함께 TypeScript 7 페이지에서 다룹니다.

에디터 설정

VS Code에는 TypeScript 지원이 내장되어 있습니다. .ts 파일을 열면 아무것도 설치하지 않아도 오류 밑줄, 자동 완성, 마우스를 올렸을 때의 타입 표시, 이름 바꾸기가 동작합니다. 에디터에서도 TypeScript 7의 속도를 원한다면, TypeScript 팀이 배포하는 전용 확장 프로그램으로 VS Code를 네이티브 TypeScript 7 언어 서버로 전환할 수 있습니다. WebStorm과 다른 JetBrains IDE는 기본으로 TypeScript를 지원하고, Neovim, Vim, Emacs, Zed, Sublime Text는 LSP 지원을 통해 TypeScript 언어 서버를 씁니다.

자주 만나는 설치 오류

This is not the tsc command you are looking for. TypeScript가 설치되지 않은 폴더에서 npx tsc를 실행해서, npx가 우연히 tsc라는 이름을 가진 폐기된 패키지를 가져온 것입니다. npm install --save-dev typescript로 진짜 패키지를 설치하세요.

tsc: command not found, 또는 Windows의 'tsc' is not recognized as an internal or external command. TypeScript가 전역으로 설치되지 않았거나, 전역 npm 폴더가 PATH에 없습니다. 로컬 설치가 있는 프로젝트에서 npx tsc를 쓰거나, 전역으로 설치한 뒤 새 터미널을 여세요.

error TS2591: Cannot find name 'process' (또는 require, __dirname은 TS2304). Node.js 자체 API의 타입은 별도 패키지에 있습니다. npm install --save-dev @types/node로 설치한 다음 compilerOptions에 "types": ["node"]를 추가하세요. TypeScript 7은 설치된 모든 @types 패키지를 더 이상 자동으로 불러오지 않습니다.

error TS5011: The common source directory of 'tsconfig.json' is './src'. 파일이 src에 있는데 outDir만 설정하고 rootDir은 설정하지 않았습니다. "rootDir": "./src"를 추가하세요.

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y는 package.json에 "type": "commonjs"를 쓰므로, tsc --init 설정(verbatimModuleSyntax와 함께 쓰는 "module": "nodenext")은 모든 .ts 파일을 CommonJS로 취급하고, 거기서는 import와 export를 쓸 수 없습니다. 이를 "type": "module"로 바꾸고, 상대 경로 import는 .js 확장자를 붙여 import { add } from "./math.js"처럼 쓰세요.

자주 묻는 질문

TypeScript는 어떻게 설치하나요?

Node.js를 설치한 다음 프로젝트 폴더에서 npm install --save-dev typescript를 실행합니다. 그러면 컴파일러가 node_modules와 package.json의 devDependencies에 추가됩니다. 실행은 npx tsc로 합니다. 컴퓨터 전체에서 쓰는 tsc 명령이 필요하면 대신 npm install -g typescript를 쓰세요.

설치된 TypeScript 버전은 어떻게 확인하나요?

프로젝트 폴더에서 npx tsc --version(또는 npx tsc -v)을 실행합니다. Version 7.0.2 같은 결과가 출력됩니다. npx 없이 tsc --version을 실행하면 전역 설치가 있을 경우 그 버전을 알려 주고, npm ls typescript는 프로젝트 의존성이 실제로 설치한 버전을 보여 줍니다.

새 TypeScript 프로젝트는 어떻게 시작하나요?

npm init -y, npm install --save-dev typescript, npx tsc --init을 차례로 실행합니다. 마지막 명령은 권장 설정이 담긴 tsconfig.json을 씁니다. 코드는 src에 두고 rootDir을 ./src로, outDir을 ./dist로 설정한 뒤, npx tsc로 컴파일하고 node dist/index.js로 결과를 실행합니다.

TypeScript는 전역으로 설치해야 하나요, 로컬로 설치해야 하나요?

로컬에, 개발 의존성으로 설치하세요. 그러면 프로젝트마다 package.json에 자신의 컴파일러 버전을 고정하고, 팀원과 CI는 npm install로 같은 버전을 받습니다. 전역 설치는 빠른 실험에 편리하지만 프로젝트가 기대하는 버전과 다를 수 있습니다.

npx tsc가 "This is not the tsc command you are looking for"라고 하는 이유는 무엇인가요?

그 폴더에 TypeScript가 설치되어 있지 않아서 npx가 tsc라는 이름의 관련 없는 폐기된 npm 패키지를 내려받았기 때문입니다. 이 패키지는 그 경고만 출력합니다. 컴파일러의 패키지 이름은 typescript입니다. 먼저 npm install --save-dev typescript를 실행하면 npx tsc가 올바른 명령을 찾습니다.