Instalacja TypeScript przez npm i sprawdzanie wersji

TypeScript to pakiet npm o nazwie typescript. Zainstaluj go w projekcie i sprawdź, czy działa:

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

Version 7.0.2

Pakiet dostarcza polecenie tsc, czyli kompilator TypeScript. Do instalacji potrzebujesz Node.js i npm (który jest dołączony do Node.js); pobierz Node.js ze strony nodejs.org albo przez menedżer pakietów systemu i sprawdź go poleceniem node --version.

Do wypróbowania TypeScript nie musisz niczego instalować. Ten blok kompiluje się i uruchamia w przeglądarce:

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

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

Instalacja TypeScript w projekcie

Zalecana jest instalacja lokalna, jako zależność deweloperska projektu:

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

npm install --save-dev typescript (w skrócie npm i -D typescript) umieszcza kompilator w node_modules i zapisuje go w package.json:

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

To zależność deweloperska, bo jest potrzebna tylko do zbudowania kodu, a nie do jego uruchomienia. Każdy, kto sklonuje projekt i uruchomi npm install, dostaje tę samą wersję kompilatora.

Żeby uruchomić lokalny kompilator, poprzedź go npx, które szuka poleceń w node_modules/.bin:

npx tsc --version

W skryptach package.json możesz pisać tsc bez npx, bo npm dodaje node_modules/.bin do PATH skryptów:

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

Wtedy npm run build kompiluje, a npm run typecheck sprawdza typy bez zapisywania żadnych plików.

Sprawdzanie wersji TypeScript

npm ls typescript

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

Jeśli npx tsc --version i tsc --version wypisują różne wersje, projekt ma własny kompilator, a globalny jest starszy albo nowszy. Dla builda projektu liczy się wersja projektu.

Instalacja TypeScript globalnie

Instalacja globalna daje polecenie tsc w każdym terminalu, bez npx:

npm install -g typescript
tsc --version

Na macOS i Linuksie może się to skończyć błędami uprawnień EACCES, gdy Node.js jest zainstalowany dla całego systemu. Instalacja Node.js przez menedżer wersji, taki jak nvm albo fnm, rozwiązuje ten problem, a sudo npm install -g nie jest zalecane.

Polecenia globalnego używaj do szybkich eksperymentów. W prawdziwym projekcie trzymaj też instalację lokalną: wtedy package.json zapisuje wersję, a aktualizacja globalnego kompilatora nie zmieni sposobu budowania projektu.

Instalacja przez pnpm, Yarn albo Bun

Każdy menedżer pakietów JavaScript instaluje ten sam pakiet:

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

Kompilator uruchamiasz przez pnpm tsc, yarn tsc albo bunx tsc.

Tworzenie tsconfig.json przez tsc --init

Plik tsconfig.json oznacza folder jako projekt TypeScript i przechowuje opcje kompilatora. Wygeneruj go:

npx tsc --init

Created a new tsconfig.json

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

Wygenerowany plik (TypeScript 7) włącza strict i kilka dodatkowych sprawdzeń, używa "module": "nodenext" i "target": "esnext" oraz ma zakomentowane linie dla rootDir i outDir. Odkomentuj te dwie, żeby kompilator czytał z src i zapisywał do dist:

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

To skrócony widok; prawdziwy plik ma więcej opcji, każdą z komentarzem. Co robią, wyjaśnia strona o tsconfig. Ponowne uruchomienie npx tsc --init w tym samym folderze kończy się błędem error TS5054: A 'tsconfig.json' file is already defined, więc nigdy nie nadpisuje twoich ustawień.

Kompilacja pierwszego pliku

Utwórz 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));
}

Potem skompiluj i uruchom:

npx tsc
node dist/index.js

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

npx tsc bez argumentów czyta tsconfig.json, sprawdza typy we wszystkich plikach, które obejmuje, i zapisuje wynik do dist. Przy wygenerowanych ustawieniach dostajesz index.js oraz index.d.ts (deklaracje typów) i pliki .map (source maps) dla każdego z nich.

Dwie rzeczy warto wiedzieć o wyniku:

• Domyślnie błędy typów nie wstrzymują generowania wyniku. tsc zgłasza błędy, kończy działanie z niezerowym kodem i mimo to zapisuje JavaScript. Ustaw "noEmitOnError": true, żeby nic nie zapisywać, dopóki są błędy.
• Gdy istnieje tsconfig.json, nie podawaj nazw plików. npx tsc src/index.ts kończy się błędem error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Uruchom samo npx tsc albo dodaj --ignoreConfig, jeśli naprawdę chcesz skompilować jeden plik z domyślnymi ustawieniami.

Tryb watch

--watch (w skrócie -w) utrzymuje kompilator w działaniu i kompiluje ponownie przy każdej zmianie pliku:

npx tsc --watch

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

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

Zostaw go otwartego w terminalu obok edytora. Zatrzymasz go skrótem Ctrl+C.

Instalacja konkretnej wersji TypeScript

Dodaj wersję po @:

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 to ostatnia wersja, której kompilator jest napisany w JavaScripcie. Niektóre narzędzia, które wywołują JavaScriptowe API kompilatora, wciąż jej potrzebują; opisuje to strona o TypeScript 7, razem ze sposobem aktualizacji.

Konfiguracja edytora

VS Code ma wbudowaną obsługę TypeScript: otwierasz plik .ts i od razu masz podkreślanie błędów, autouzupełnianie, typy po najechaniu kursorem i zmianę nazw bez instalowania czegokolwiek. Jeśli chcesz szybkości TypeScript 7 w edytorze, zespół TypeScript publikuje osobne rozszerzenie, które przełącza VS Code na natywny serwer językowy TypeScript 7. WebStorm i inne IDE JetBrains obsługują TypeScript od razu, a Neovim, Vim, Emacs, Zed i Sublime Text korzystają z serwera językowego TypeScript przez swoją obsługę LSP.

Najczęstsze błędy przy instalacji

This is not the tsc command you are looking for. Uruchamiasz npx tsc w folderze bez zainstalowanego TypeScript, a npx pobiera przestarzały pakiet, który akurat nazywa się tsc. Zainstaluj właściwy przez npm install --save-dev typescript.

tsc: command not found albo 'tsc' is not recognized as an internal or external command w Windows. TypeScript nie jest zainstalowany globalnie albo globalny folder npm nie jest w PATH. Użyj npx tsc w projekcie z instalacją lokalną albo zainstaluj go globalnie i otwórz nowy terminal.

error TS2591: Cannot find name 'process' (albo require; __dirname daje TS2304). Własne API Node.js ma typy w osobnym pakiecie. Zainstaluj go przez npm install --save-dev @types/node, a potem dodaj "types": ["node"] do compilerOptions: TypeScript 7 nie ładuje już automatycznie wszystkich zainstalowanych pakietów @types.

error TS5011: The common source directory of 'tsconfig.json' is './src'. Pliki są w src, a ustawiono outDir, ale nie rootDir. Dodaj "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y zapisuje "type": "commonjs" w package.json, więc konfiguracja z tsc --init ("module": "nodenext" z verbatimModuleSyntax) traktuje każdy plik .ts jako CommonJS, gdzie import i export są niedozwolone. Zmień to na "type": "module" i pisz względne importy z rozszerzeniem .js: import { add } from "./math.js".