Kurs JavaScript i TypeScript · Moduł 6: Podstawy TypeScript

Konfiguracja TypeScript i narzędzia

5 min czytania ·
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ądarkami
  • ES2020 - 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 jak Promise.allSettled, BigInt
  • WebWorker - 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:

  1. Automatyczne - TypeScript generuje je z flagą declaration: true
  2. Ręczne - piszesz sam dla kodu JS bez typów
  3. 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/jest

TypeScript 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życiem any
  • no-unused-vars - wykrywa nieużywane zmienne (z obsługą TypeScript)
  • prefer-nullish-coalescing - preferuj ?? zamiast ||
  • prefer-optional-chain - preferuj a?.b zamiast a && a.b
  • strict-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. 1. Którą z poniższych flag NIE włącza opcja "strict": true w tsconfig.json?

  2. 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:

  1. PytanieFlagi nieobjęte opcją strict
  2. PytanieDeclaration files (.d.ts)
  3. Zadanie z kodemStrict mode - praktyka
  4. PytanieDefinitelyTyped (@types/*)
  5. Zadanie z kodemDeclaration files - praktyka
  6. Ułóż w kolejnościKolejność opcji tsconfig - od podstawowych do zaawansowanych
  7. Kliknij w kolejnościSkładnia path alias w tsconfig
  8. Ułóż w kolejnościKonfiguracja projektu TypeScript
  9. PytanieTyp never

Przydatne artykuły