Kurs JavaScript i TypeScript · Moduł 6: Podstawy TypeScript
Konfiguracja TypeScript i narzędzia
W tej lekcji7
W Parku Jurajskim nawet najlepszy system genetyczny jest bezużyteczny bez właściwej kalibracji sprzętu laboratoryjnego. Tak samo TypeScript bez odpowiedniej konfiguracji nie wykorzysta swojego pełnego potencjału. Plik tsconfig.json to Twój panel sterowania - definiuje, jak kompilator TypeScript interpretuje i transformuje Twój kod.
tsconfig.json - centrum dowodzenia
Każdy projekt TypeScript zaczyna się od pliku tsconfig.json w katalogu głównym. To plik JSON definiujący opcje kompilatora, które pliki mają być kompilowane i jak ma wyglądać wynik:
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}Kluczowe opcje kompilatora
Target - wersja JavaScript na wyjściu:
ES5- kompatybilność ze starszymi przeglądarkamiES2020- nowoczesne środowiska (nullish coalescing, optional chaining)ESNext- najnowsze funkcje
Module - system modułów:
CommonJS- Node.js (require/module.exports)ESNext- moduły ES (import/export)NodeNext- Node.js z obsługą ESM
Lib - jakie API są dostępne:
DOM- API przeglądarki (document, window)ES2020- metody jakPromise.allSettled,BigIntWebWorker- API Web Workers
Strict Mode - maksymalne bezpieczeństwo
Flaga strict: true włącza wszystkie rygorystyczne sprawdzenia jednocześnie. To jak włączenie pełnych zabezpieczeń w Parku Jurajskim - żaden dinozaur nie wymknie się z zagrody:
// strict: true włącza WSZYSTKIE poniższe:
{
"strictNullChecks": true, // null/undefined muszą być obsłużone
"strictFunctionTypes": true, // ścisłe typowanie parametrów funkcji
"strictBindCallApply": true, // ścisłe typowanie bind/call/apply
"strictPropertyInitialization": true, // właściwości muszą być zainicjalizowane
"noImplicitAny": true, // zakaz niejawnego any
"noImplicitThis": true, // this musi mieć typ
"alwaysStrict": true, // "use strict" w każdym pliku
"useUnknownInCatchVariables": true // catch(e) to unknown, nie any
}Przykład różnicy z strictNullChecks:
// BEZ strictNullChecks - błąd w runtime!
function getDinoName(id: string): string {
const dino = dinosaurs.find(d => d.id === id);
return dino.name; // Runtime error: Cannot read property 'name' of undefined
}
// Z strictNullChecks - TypeScript wymusza obsługę null
function getDinoName(id: string): string | undefined {
const dino = dinosaurs.find(d => d.id === id);
return dino?.name; // Bezpieczne - zwraca undefined jeśli nie znaleziono
}Path Aliases - skróty nawigacyjne
W dużych projektach importy mogą stać się nieczytelne. Path aliases pozwalają tworzyć skróty:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@models/*": ["src/models/*"],
"@utils/*": ["src/utils/*"],
"@services/*": ["src/services/*"],
"@config": ["src/config/index.ts"]
}
}
}Zamiast:
import { Dinosaur } from '../../../models/dinosaur';
import { formatDate } from '../../utils/helpers';Piszesz:
import { Dinosaur } from '@models/dinosaur';
import { formatDate } from '@utils/helpers';Declaration Files (.d.ts)
Pliki deklaracji opisują typy dla kodu JavaScript. Mają rozszerzenie .d.ts i nie zawierają implementacji - tylko sygnatury typów:
// dinosaur.d.ts - deklaracja typów
declare interface IDinosaur {
id: string;
name: string;
species: string;
dangerLevel: 1 | 2 | 3 | 4 | 5;
}
declare function findDinosaur(id: string): IDinosaur | null;
declare const PARK_NAME: string;
// Deklaracja modułu dla biblioteki JS bez typów
declare module 'dino-tracker' {
export function trackPosition(id: string): [number, number];
export function getStatus(id: string): 'active' | 'sleeping' | 'escaped';
}Trzy rodzaje plików deklaracji:
- Automatyczne - TypeScript generuje je z flagą
declaration: true - Ręczne - piszesz sam dla kodu JS bez typów
- DefinitelyTyped - społecznościowe typy dla popularnych bibliotek
DefinitelyTyped (@types/*)
Wiele bibliotek JavaScript nie ma wbudowanych typów. Repozytorium DefinitelyTyped zawiera typy tworzone przez społeczność:
# Instalacja typów dla popularnych bibliotek
npm install --save-dev @types/node
npm install --save-dev @types/express
npm install --save-dev @types/lodash
npm install --save-dev @types/jestTypeScript automatycznie rozpoznaje pakiety @types/* - nie musisz ich importować. Jeśli biblioteka ma wbudowane typy (jak axios czy date-fns), nie potrzebujesz osobnego pakietu @types.
Opcja typeRoots w tsconfig kontroluje, skąd TypeScript ładuje typy:
{
"compilerOptions": {
"typeRoots": ["./node_modules/@types", "./src/types"]
}
}ESLint z TypeScript
TypeScript ma własne sprawdzenia typów, ale ESLint z pluginem @typescript-eslint dodaje reguły stylistyczne i zaawansowane analizy:
{
"parser": "@typescript-eslint/parser",
"plugins": ["@typescript-eslint"],
"extends": [
"eslint:recommended",
"plugin:@typescript-eslint/recommended",
"plugin:@typescript-eslint/recommended-requiring-type-checking"
],
"parserOptions": {
"project": "./tsconfig.json"
},
"rules": {
"@typescript-eslint/no-explicit-any": "warn",
"@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
"@typescript-eslint/prefer-nullish-coalescing": "error",
"@typescript-eslint/prefer-optional-chain": "error"
}
}Najważniejsze reguły @typescript-eslint:
no-explicit-any- ostrzega przed użyciemanyno-unused-vars- wykrywa nieużywane zmienne (z obsługą TypeScript)prefer-nullish-coalescing- preferuj??zamiast||prefer-optional-chain- preferuja?.bzamiasta && a.bstrict-boolean-expressions- zabrania niejawnych konwersji boolean
Opcje jakości kodu
Dodatkowe flagi kompilatora pomagające utrzymać jakość kodu:
{
"compilerOptions": {
"noUnusedLocals": true, // błąd przy nieużywanych zmiennych
"noUnusedParameters": true, // błąd przy nieużywanych parametrach
"noImplicitReturns": true, // każda ścieżka musi zwracać wartość
"noFallthroughCasesInSwitch": true, // wymusza break w switch
"noUncheckedIndexedAccess": true, // arr[i] to T | undefined
"exactOptionalPropertyTypes": true // undefined !== pominięcie pola
}
}Opcja noUncheckedIndexedAccess jest szczególnie przydatna - zabezpiecza przed błędami indeksowania:
const dinos = ["T-Rex", "Raptor", "Triceratops"];
// BEZ noUncheckedIndexedAccess
const first: string = dinos[0]; // OK, ale dinos[100] też byłoby "string"!
// Z noUncheckedIndexedAccess
const first: string | undefined = dinos[0]; // TypeScript wymusza sprawdzenie
if (first) {
console.log(first.toUpperCase()); // Bezpieczne
}Kod do tej lekcji: index.ts
// Konfiguracja TypeScript - Laboratorium Parku Jurajskiego
// === 1. STRICT MODE W AKCJI ===
// strictNullChecks - wymusza obsluge null/undefined
interface IDinosaur {
id: string;
name: string;
species: string;
dangerLevel: 1 | 2 | 3 | 4 | 5;
}
const dinosaurs: IDinosaur[] = [
{ id: "001", name: "Rexy", species: "T-Rex", dangerLevel: 5 },
{ id: "002", name: "Blue", species: "Velociraptor", dangerLevel: 4 },
{ id: "003", name: "Bumpy", species: "Ankylosaurus", dangerLevel: 2 },
];
// Bezpieczne wyszukiwanie z obsluga undefined
function findDino(id: string): IDinosaur | undefined {
return dinosaurs.find(d => d.id === id);
}
const dino = findDino("001");
if (dino) {
console.log("Znaleziono:", dino.name, "- poziom zagrozenia:", dino.dangerLevel);
} else {
console.log("Nie znaleziono dinozaura");
}
// === 2. PATH ALIASES (symulacja) ===
// W prawdziwym projekcie:
// import { Dinosaur } from '@models/dinosaur';
// import { formatDate } from '@utils/helpers';
// Zamiast: import { Dinosaur } from '../../../models/dinosaur';
// === 3. DECLARATION FILES (.d.ts) ===
// Symulacja deklaracji typow dla biblioteki JS
// Tak wygladalby plik dino-tracker.d.ts:
// declare module 'dino-tracker' {
// export function trackPosition(id: string): [number, number];
// export function getStatus(id: string): DinoStatus;
// }
// Uzywamy typow tak, jakby istniala biblioteka:
type DinoStatus = "active" | "sleeping" | "escaped";
function getStatus(id: string): DinoStatus {
const dino = findDino(id);
if (!dino) return "escaped";
return dino.dangerLevel >= 4 ? "active" : "sleeping";
}
console.log("Status Rexy:", getStatus("001"));
console.log("Status Blue:", getStatus("002"));
// === 4. noUncheckedIndexedAccess ===
const species = ["T-Rex", "Raptor", "Triceratops"];
// Z noUncheckedIndexedAccess: species[0] to string | undefined
const first = species[0];
if (first !== undefined) {
console.log("Pierwszy gatunek:", first.toUpperCase());
}
// === 5. DEFINITELYTYPED ===
// Instalacja typow:
// npm install --save-dev @types/node @types/express @types/lodash
// TypeScript automatycznie je rozpoznaje
// === 6. ESLINT Z TYPESCRIPT ===
// Przyklady regul @typescript-eslint:
// prefer-nullish-coalescing: uzywaj ?? zamiast ||
const parkName: string | null = null;
const displayName = parkName ?? "Jurassic Park"; // lepsze niz ||
console.log("Park:", displayName);
// prefer-optional-chain: uzywaj ?. zamiast &&
interface ParkConfig {
security?: {
fences?: {
voltage?: number;
};
};
}
const config: ParkConfig = { security: { fences: { voltage: 10000 } } };
const voltage = config.security?.fences?.voltage; // lepsze niz config && config.security && ...
console.log("Napiecie ogrodzenia:", voltage, "V");
// noImplicitReturns: kazda sciezka musi zwracac wartosc
function classifyThreat(level: number): string {
if (level >= 4) return "WYSOKIE ZAGROZENIE";
if (level >= 2) return "SREDNIE ZAGROZENIE";
return "NISKIE ZAGROZENIE"; // wymagane przez noImplicitReturns
}
console.log("Klasyfikacja (5):", classifyThreat(5));
console.log("Klasyfikacja (1):", classifyThreat(1));Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Którą z poniższych flag NIE włącza opcja "strict": true w tsconfig.json?
2. Jaka jest rola plików .d.ts (declaration files) w TypeScript?
To 2 z 4 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Napraw problemy ze strict mode: strictNullChecks, noUncheckedIndexedAccess, noImplicitReturns i skonfiguruj path aliases.
- Edytor kodu
Napisz interfejs SecurityEvent, zaimplementuj checkPerimeter i logEvent, oraz stwórz typ DinoSize z funkcją classifyBySize.
- Układanie w pionie
Uporządkuj opcje tsconfig od najważniejszych (włączaj najpierw) do zaawansowanych:
- Klikanie w kolejności
Ułóż elementy konfiguracji path alias w tsconfig.json:
- Układanie w pionie
Uporządkuj kroki tworzenia nowego projektu TypeScript:
Zadania po tej lekcji
- PytanieFlagi nieobjęte opcją strict
- PytanieDeclaration files (.d.ts)
- Zadanie z kodemStrict mode - praktyka
- PytanieDefinitelyTyped (@types/*)
- Zadanie z kodemDeclaration files - praktyka
- Ułóż w kolejnościKolejność opcji tsconfig - od podstawowych do zaawansowanych
- Kliknij w kolejnościSkładnia path alias w tsconfig
- Ułóż w kolejnościKonfiguracja projektu TypeScript
- PytanieTyp never