"declaration"

Generuje pliki .d.ts z typami obok skompilowanego JavaScriptu.

Na tej stronie

Przykład
Definicja i zastosowanie
Składnia
Więcej przykładów
Dobre praktyki
Powiązane hasła

Przykład

JSON

{
  "compilerOptions": {
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

Definicja i zastosowanie

Przy declaration: true kompilator obok każdego pliku .js zapisuje plik .d.ts. Zawiera on same typy: sygnatury funkcji, interfejsy, typy klas i stałych, bez żadnej implementacji.

To niezbędne przy publikowaniu biblioteki w npm. Użytkownik dostaje działający JavaScript i typy, dzięki którym edytor podpowiada i sprawdza wywołania. Ścieżkę do deklaracji wskazuje się w package.json polem types albo warunkiem types w polu exports.

Opcje pokrewne: declarationDir zapisuje deklaracje w osobnym folderze, emitDeclarationOnly generuje wyłącznie pliki .d.ts (gdy JavaScript buduje inne narzędzie), a declarationMap pozwala w edytorze przejść z typu prosto do pliku źródłowego .ts.

Składnia

"declaration": true

Więcej przykładów

Źródło i wygenerowana deklaracja

TypeScript

// src/progress.ts
export interface Progress {
  done: number
  total: number
}

export function percent(progress: Progress): number {
  return Math.round((progress.done / progress.total) * 100)
}

// dist/progress.d.ts (wygenerowany):
// export interface Progress {
//     done: number;
//     total: number;
// }
// export declare function percent(progress: Progress): number;

package.json biblioteki

JSON

{
  "name": "@codeworlds/progress",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/progress.d.ts",
      "default": "./dist/progress.js"
    }
  }
}

Dobre praktyki

Aplikacje, np. na Next.js czy Vite, nie potrzebują deklaracji. Włączaj declaration w bibliotekach i pakietach współdzielonych w monorepo.
Zapisuj jawnie typy zwracane przez eksportowane funkcje. Deklaracje są wtedy czytelniejsze, a opcja isolatedDeclarations (TypeScript 5.5) wręcz tego wymaga, żeby inne narzędzia mogły generować .d.ts bez pełnego sprawdzania typów.

Powiązane hasła

Widzisz błąd albo brakuje przykładu? Napisz do nas.

Darmowy kursPrzećwicz TypeScript w kursie JavaScript i TypeScriptZadania z podpowiedziami, edytor kodu i postępy zapisywane na bieżąco.Zobacz kurs