TypeScript Academy · Lekcja

Publikowanie biblioteki narzędzi typów

Pakuj i udostępniaj niestandardowe typy narzędziowe w npm.

Publikowanie biblioteki narzędzi typów to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej TypeScript Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs TypeScript Academy zawiera 4 lekcji w sumie.

Czym jest biblioteka typów narzędziowych

Biblioteka typów narzędziowych eksportuje wyłącznie typy TypeScriptu — nie zawiera kodu wykonywanego w czasie działania. Popularne przykłady to type-fest, ts-essentials i utility-types.

// A type utility library exports types like:
export type DeepPartial<T> = T extends object
  ? { [K in keyof T]?: DeepPartial<T[K]> }
  : T;

Struktura projektu

Zachowaj prostą strukturę: pojedynczy plik src/index.ts, który ponownie eksportuje wszystkie narzędzia, oraz plik tsconfig.json skonfigurowany tak, aby generować wyłącznie deklaracje.

// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "dist",
    "strict": true
  }
}

package.json dla pakietu zawierającego tylko typy

Ustaw pola main i types, aby wskazywały na deklaracje. Ustaw sideEffects: false, aby umożliwić tree-shaking.

{
  "name": "@myorg/type-utils",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "sideEffects": false,
  "files": ["dist"]
}

Generowanie deklaracji

Uruchom tsc, aby wygenerować pliki .d.ts. W bibliotece zawierającej wyłącznie typy wynik JavaScriptu jest pusty lub minimalny.

# Build declarations
npx tsc
# dist/index.d.ts is generated

Wersjonowanie i dzienniki zmian

Należy stosować semantyczne wersjonowanie: przełomowe zmiany typów wymagają zwiększenia wersji major, nowe narzędzia — minor, a poprawki — patch.

# Bump version
npm version minor
# Generate changelog with conventional-changelog or changesets

Publikowanie w npm

Należy użyć npm publish lub pnpm publish. W przypadku pakietów ze scope należących do organizacji należy upewnić się, że użytkownik jest zalogowany, a scope jest skonfigurowany.

npm login
npm publish --access public
# or for private: npm publish --access restricted

Zgodność wersji TypeScript

Należy udokumentować minimalną wersję TypeScript wymaganą przez narzędzia. Rekurencyjne typy warunkowe wymagają TS 4.1+, a Awaited jest wbudowany od TS 4.5+.

// package.json peerDependencies
{
  "peerDependencies": {
    "typescript": ">=4.5"
  }
}

Testowanie typów za pomocą tsd

Należy użyć pakietu tsd do pisania testów na poziomie typów, uruchamianych podczas CI w celu sprawdzenia poprawności działania narzędzi.

import { expectType } from "tsd";
import type { DeepPartial } from "@myorg/type-utils";

expectType<DeepPartial<{ a: { b: number } }>>({ a: {} });

Dokumentacja za pomocą TSDoc

Należy dodawać do typów komentarze JSDoc w formacie /** */. Narzędzia takie jak TypeDoc generują na ich podstawie dokumentację API.

/**
 * Makes all properties of T optional at every depth.
 * @example type A = DeepPartial<{ x: { y: number } }> // { x?: { y?: number } }
 */
export type DeepPartial<T> = ...

Dystrybucja w monorepo

W monorepo należy publikować pakiet typów jako pakiet workspace, aby inne aplikacje korzystały z niego za pomocą workspace:* zamiast npm.

// Other package's package.json
{
  "dependencies": {
    "@myorg/type-utils": "workspace:*"
  }
}

Podsumowanie: publikowanie bibliotek typów

Biblioteka narzędzi typów powinna używać emitDeclarationOnly: true, eksportować typy z src/index.ts, być wersjonowana zgodnie z semver, testowana za pomocą tsd, opisana przy użyciu TSDoc i publikowana w npm lub rejestrze workspace.

Szybkie sprawdzenie

Jaka opcja tsconfig generuje wyłącznie pliki .d.ts, bez kodu JavaScript?

Czego się Państwo nauczyli

Publikowanie biblioteki narzędzi typów wymaga użycia emitDeclarationOnly, odpowiednich pól w package.json, testów na poziomie typów z użyciem tsd, komentarzy TSDoc i semantycznego wersjonowania. Dzięki temu można udostępniać narzędzia społeczności lub współdzielić je w monorepo.

Często zadawane pytania

Czy lekcja „Publikowanie biblioteki narzędzi typów” jest bezpłatna?

Tak — pełny tekst „Publikowanie biblioteki narzędzi typów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu TypeScript Academy, przejdź na CoddyKit PRO. Kurs TypeScript Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Publikowanie biblioteki narzędzi typów”?

Pakuj i udostępniaj niestandardowe typy narzędziowe w npm. Ćwiczysz TypeScript Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć TypeScript Academy?

Nie wymagamy żadnego doświadczenia. TypeScript Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Publikowanie biblioteki narzędzi typów”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji TypeScript Academy?

Tak. Każda lekcja TypeScript Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do TypeScript Academy