Kurs vibe coding z Claude Code · Moduł 2: Projekt Next.js z Claude Code

TypeScript: typy jako sprawdzian dla Claude

10 min czytania ·
W tej lekcji16

Ahoj! Kraken's Call ma już sekcję hero. Teraz poznasz narzędzie, które sprawdza kod Claude, zanim zobaczy go choćby jeden gracz: TypeScript i jego kompilator.

Problem: Claude pisze pewnie, a błąd widzi gracz

Claude pisze szybko i pewnie, ale czasem wpisze poziom pirata jako tekst "5" zamiast liczby 5 albo sięgnie po pole, którego obiekt nie ma. W zwykłym JavaScripcie taki błąd wychodzi dopiero w przeglądarce, u gracza. TypeScript łapie go wcześniej, podczas sprawdzianu, który Claude może uruchomić sam, zanim zamelduje "gotowe". Typów nie piszesz ręcznie: masz je umieć przeczytać i wymagać, żeby sprawdzian przeszedł uczciwie.

TypeScript w jednym akapicie

TypeScript to JavaScript z systemem typów. Typ mówi, jaka wartość może trafić w dane miejsce: tekst, liczba albo obiekt o określonych polach. Pliki .ts i .tsx są kompilowane do zwykłego JavaScriptu, więc przeglądarka typów nie widzi. Oto funkcja, która oczekuje tekstu:

function greet(name: string) {
  return "Ahoj, " + name;
}

greet(5);

Zapis name: string mówi, że parametr ma być tekstem, więc przy greet(5) kompilator zgłosi błąd, zanim kod w ogóle ruszy. Czego typy nie zrobią: po kompilacji znikają, więc nie sprawdzą danych, które strona dostanie w trakcie działania, na przykład z internetu.

Sprawdzian: kompilator jako bosman

tsc to kompilator TypeScriptu. W projekcie Next.js służy przede wszystkim do sprawdzenia typów w całym projekcie jedną komendą:

npx tsc --noEmit

npx z lekcji 1_1 uruchamia tsc zainstalowany w projekcie, a --noEmit znaczy: tylko sprawdź, nie zapisuj plików JavaScript. Gdy typy się zgadzają, komenda nic nie wypisuje, więc cisza to dobry znak. Dokumentacja Next.js poleca ją do sprawdzania typów przed buildem.

Drugi sprawdzian znasz z lekcji 1_2: npm run build też sprawdza typy (linia "Running TypeScript") i przerywa się przy błędzie. Pułapka: typ LayoutProps z app/layout.tsx Next.js generuje dopiero przy npm run dev albo npm run build, więc w świeżo pobranym projekcie tsc zgłosi "Cannot find name 'LayoutProps'", dopóki raz go nie zbudujesz. Rada kapitana: proś o oba sprawdziany, szybki tsc między krokami i build na koniec.

Typy podstawowe

Najprostsze typy to string (tekst), number (liczba) i boolean (prawda albo fałsz). Typ zapisuje się po dwukropku, zaraz za nazwą zmiennej:

const shipName: string = "Black Pearl";
const crewCount: number = 3;
const isSailing: boolean = true;
const ports: string[] = ["Tortuga", "Nassau"];

Ostatnia linia to tablica: string[] znaczy "lista tekstów". W kodzie od Claude typ często nie jest dopisany, bo TypeScript wywnioskuje go z wartości: po let crewSize = 3 próba wpisania tam tekstu też skończy się błędem.

Interface: umowa o kształcie obiektu

Sekcja "Załoga" przyszłego landing page'a pokaże karty piratów. Każdy pirat to obiekt z kilkoma polami, a interface to umowa, która mówi, jakie pola ma mieć taki obiekt i jakiego są typu:

interface CrewMember {
  name: string;
  role: string;
  level: number;
}

Od teraz każdy obiekt opisany jako CrewMember musi mieć imię i rolę jako tekst oraz poziom jako liczbę. Interface niczego nie wyświetla ani nie tworzy: to kształt, którego pilnuje kompilator.

Pole opcjonalne i unia

Nie każdy pirat ma papugę, więc to pole będzie opcjonalne: oznacza je znak zapytania po nazwie. Rola z kolei nie powinna być dowolnym tekstem, tylko jedną z kilku znanych. Do tego służy unia (union type), czyli typ złożony z kilku możliwości połączonych znakiem |, który czytasz jako "albo":

type CrewRole = "kapitan" | "sternik" | "kucharz" | "bosman";

interface CrewMember {
  name: string;
  role: CrewRole;
  level: number;
  parrot?: string;
}

Słowo type nadaje nazwę dowolnemu typowi, tu unii czterech napisów. Rola "kapitan" przejdzie, a "kapitn" z literówką już nie: kompilator odpowie "Type '"kapitn"' is not assignable to type 'CrewRole'" i jeszcze podpowie poprawną wartość. Pole parrot? wolno pominąć, ale kod musi sprawdzić, czy papuga istnieje, zanim jej użyje.

type czy interface?

Obie formy opisują kształt obiektu i zwykle są wymienne, ale unię zapiszesz tylko przez type. Dokumentacja TypeScriptu radzi: używaj interface, dopóki nie potrzebujesz czegoś, co daje tylko type. Ja się tego trzymam ale gdy Claude opisze obiekt przez type, nie każ mu tego zmieniać: to nie błąd.

Polecenie dla Claude Code

Czas, żeby Claude zbudował stronę załogi z typami i sam ją sprawdził. W sesji w folderze krakens-call, nadal w trybie Manual, wydaj polecenie:

Polecenie dla Claude Code:

Dodaj stronę app/crew/page.tsx z sekcją "Załoga" dla Kraken's Call:
trzy karty piratów (imię, rola, poziom, opcjonalnie imię papugi).
W tym pliku zdefiniuj interface CrewMember, rolę jako unię kilku
napisów i komponent CrewCard z typowanymi propsami. Bez any, bez as,
bez @ts-ignore i bez zmian w tsconfig.json i next.config.ts. Klasy
Tailwind w stylu @app/page.tsx. Na koniec uruchom npx tsc --noEmit
i npm run build i pokaż oba wyniki.

Zakazy z czwartego zdania zamykają drogi na skróty, o których za chwilę, a ostatnie zdanie żąda dowodu: dwóch wyników zamiast słowa "gotowe".

Co napisał Claude

Otwórz w Cursorze app/crew/page.tsx. Na górze stoją znane Ci już CrewRole i CrewMember, a pod nimi dane załogi:

const crew: CrewMember[] = [
  { name: "Anne Bonny", role: "kapitan", level: 10, parrot: "Kapitan Pióro" },
  { name: "Jack Rackham", role: "sternik", level: 7 },
  { name: "Mary Read", role: "kucharz", level: 5 },
];

CrewMember[] to tablica obiektów zgodnych z umową. Papugę ma tylko pierwsza piratka, bo pole jest opcjonalne. Dane są wpisane w pliku: strona niczego nie pobiera z internetu.

Dalej komponent jednej karty. Propsy to dane, które komponent dostaje od rodzica, podobnie jak funkcja dostaje argumenty, a ich kształt też opisuje interface:

interface CrewCardProps {
  member: CrewMember;
}

function CrewCard({ member }: CrewCardProps) {
  return (
    <article className="rounded-lg border border-yellow-500 bg-gray-900 p-6 text-white">
      <h3 className="text-xl font-bold">{member.name}</h3>
      <p className="mt-2 text-gray-300">
        {member.role}, poziom {member.level}
      </p>
      {member.parrot && (
        <p className="mt-2 text-yellow-400">Papuga: {member.parrot}</p>
      )}
    </article>
  );
}

{ member }: CrewCardProps mówi, że karta przyjmuje jeden prop member typu CrewMember. Zapis member.parrot && (...) pokazuje akapit z papugą tylko wtedy, gdy pole istnieje: tak wygląda sprawdzenie pola opcjonalnego. Gdyby Claude napisał member.ship, kompilator zgłosiłby, że takiego pola w umowie nie ma.

Na końcu pliku strona, która układa karty w siatce:

export default function CrewPage() {
  return (
    <main className="min-h-screen bg-black px-6 py-16">
      <h1 className="text-center text-3xl font-bold text-red-600">Załoga</h1>
      <div className="mx-auto mt-8 grid max-w-4xl grid-cols-1 gap-4 md:grid-cols-3">
        {crew.map((member) => (
          <CrewCard key={member.name} member={member} />
        ))}
      </div>
    </main>
  );
}

crew.map tworzy kartę dla każdego pirata, a key daje Reactowi niepowtarzalną etykietę elementu listy. Siatkę znasz z lekcji 1_3. Plik leży w folderze app/crew/, więc strona będzie pod adresem /crew.

Dowód: dwa wyniki

Claude pokaże wynik obu komend. Po npx tsc --noEmit nie ma żadnego tekstu, a build kończy się tak:

✓ Compiled successfully in 1523ms
  Running TypeScript ...
  Finished TypeScript in 745ms ...

Route (app)
┌ ○ /
├ ○ /_not-found
└ ○ /crew

Linia /crew potwierdza, że strona istnieje, a linie o TypeScripcie, że typy się zgadzają. Otwórz jeszcze http://localhost:3000/crew: build sprawdza kod, ale czytelności kart za Ciebie nie oceni.

Jak wygląda błąd typów

Zobacz, co by się stało, gdyby Claude wpisał poziom Mary Read jako tekst "5". npx tsc --noEmit wypisałby jedną linię:

app/crew/page.tsx(13,41): error TS2322: Type 'string' is not assignable to type 'number'.

Czytasz od lewej: plik, linia i kolumna, kod błędu i opis: w polu level stoi tekst, a umowa wymaga liczby. npm run build wypisze ten sam komunikat i skończy słowami "Failed to type check.", więc zepsuta wersja nie powstanie.

Ten sam błąd zobaczysz w Cursorze bez komend. Cursor jest zbudowany na kodzie VS Code, więc działa w nim to, co dokumentacja VS Code opisuje dla TypeScriptu: błędy są zaznaczone w tekście pliku, a po najechaniu kursorem na nazwę widzisz jej typ, na przykład CrewMember przy member. Listę błędów pokaże panel Problems (Cmd+Shift+M na Macu, Ctrl+Shift+M na Windowsie i Linuksie).

Typowy błąd agenta: wyciszanie zamiast naprawy

Gdy sprawdzian nie przechodzi, agent bywa kuszony, żeby go uciszyć zamiast naprawić przyczynę. Sprawdzian wtedy przechodzi, bo przestał patrzeć. Rozpoznasz cztery sztuczki:

  • as any: as to asercja typu, czyli "wiem lepiej", a any wyłącza sprawdzanie;
  • // @ts-ignore albo // @ts-expect-error nad linią z błędem: kompilator tę linię pomija;
  • "strict": false w tsconfig.json: znikają ścisłe sprawdzenia, na przykład ostrzeżenie "'captain' is possibly 'undefined'", że szukany pirat może nie istnieć;
  • ignoreBuildErrors: true w next.config.ts: build w ogóle nie sprawdza typów, co dokumentacja Next.js nazywa wprost niebezpiecznym.

Tak wygląda pierwsza sztuczka w diffie w Source Control:

-  { name: "Mary Read", role: "kucharz", level: "5" },
+  { name: "Mary Read", role: "kucharz", level: "5" as any },

Prawdziwa poprawka zmieniłaby "5" na 5, a ta zostawia tekst tam, gdzie umowa wymaga liczby. Asercja znika po kompilacji jak każdy typ, więc niczego nie naprawia: błąd tylko schował się przed kompilatorem.

Jak to wyłapać: w diffie szukaj any, as i @ts-, a w Source Control sprawdź, czy nie zmieniły się tsconfig.json ani next.config.ts. Pomaga też linter: w projekcie z create-next-app komenda npm run lint zgłasza as any jako błąd "Unexpected any" i odrzuca @ts-ignore. Gdy znajdziesz taką sztuczkę, odpowiedz:

Usuń as any z app/crew/page.tsx i napraw przyczynę: level ma być
liczbą zgodną z CrewMember. Nie zmieniaj tsconfig.json. Potem uruchom
npx tsc --noEmit i npm run lint i pokaż oba wyniki.

Odpowiedź nazywa przyczynę, zamyka drogę na skróty i znów żąda dowodu.

Spotkasz w kodzie Claude

Tych zapisów nie musisz pisać: wystarczy, że je rozpoznasz w kodzie od Claude.

Generyki to typy z parametrem w nawiasach ostrych: Array<CrewMember> znaczy to samo co CrewMember[]. Tak opisuje się na przykład odpowiedź serwera o zmiennej zawartości:

interface ApiResponse<T> {
  data: T;
  status: number;
}

const answer: ApiResponse<CrewMember[]> = { data: crew, status: 200 };

T to miejsce na typ, który podajesz przy użyciu, tu listę piratów. Przedrostek Api jest celowy: Response w pliku bez importów i eksportów zderza się z wbudowanym typem przeglądarki, a tsc zgłasza "All declarations of 'Response' must have identical type parameters".

Typy narzędziowe (utility types) budują nowy typ z istniejącego. Partial robi wszystkie pola opcjonalnymi, Pick wybiera kilka z nich, a Omit kilka pomija:

type CrewDraft = Partial<CrewMember>;
type CrewBadge = Pick<CrewMember, "name" | "role">;
type CrewWithoutParrot = Omit<CrewMember, "parrot">;

CrewBadge ma tylko imię i rolę, w sam raz na małą plakietkę, a Required działa odwrotnie do Partial. Żaden z tych zapisów nie zmienia samego CrewMember: obok niego powstają nowe nazwy.

unknown zamiast any. Oba typy przyjmą każdą wartość, ale unknown nie pozwoli jej użyć, dopóki nie sprawdzisz, czym jest:

function shout(value: unknown) {
  if (typeof value === "string") {
    return value.toUpperCase();
  }
  return "???";
}

Wewnątrz if TypeScript wie już, że value to tekst, więc toUpperCase() jest dozwolone, a z any przepuściłby wywołanie dowolnej metody. Rzadziej zobaczysz never, czyli typ wartości, która nigdy nie powstanie, na przykład wyniku funkcji, która zawsze rzuca błąd.

tsconfig.json: ustawienia kompilatora

Ustawienia TypeScriptu leżą w pliku tsconfig.json, który utworzył kreator. Najważniejsza jest dla Ciebie ta linia:

"strict": true,

strict włącza całą rodzinę ścisłych sprawdzeń, między innymi noImplicitAny, które zgłasza miejsca, gdzie typ po cichu stałby się any, i strictNullChecks, które pilnuje wartości null i undefined. Każda propozycja zmiany tej linii to sygnał, żeby zatrzymać Claude.

Przegląd kapitana

Zanim zatwierdzisz stronę załogi, sprawdź:

  1. Uczciwy sprawdzian: w diffie nie ma any, as ani @ts-, a na liście zmian nie ma tsconfig.json i next.config.ts.
  2. Dowód, nie meldunek: widziałeś pusty wynik npx tsc --noEmit i tabelę builda z /crew.
  3. Typy opisują dane: w CrewMember są pola, które widać na kartach, bez wymyślonych na zapas.
  4. Strona: pod /crew stoją trzy karty, a na wąskim ekranie jedna pod drugą.

Typowy błąd agenta już znasz: wyciszenie błędu typów zamiast naprawy. Najpewniej złapiesz go, gdy do dwóch sprawdzianów z polecenia dołożysz trzeci, npm run lint.

Następny krok

Z commitem poczekaj: w następnej lekcji zrobisz go po przeglądzie zmian i wyślesz projekt na GitHub. W edytorze poniżej stoi ta sama strona załogi z typami: dopisz bosmana z papugą i zobacz go w podglądzie.

Pamiętaj: typy to mapa z zaznaczonymi mieliznami, a kompilator to bosman, który sprawdza kurs, zanim okręt wypłynie.

Kod do tej lekcji: App.tsx
// Kraken's Call - strona załogi opisana typami TypeScript

type CrewRole = "kapitan" | "sternik" | "kucharz" | "bosman";

interface CrewMember {
  name: string;
  role: CrewRole;
  level: number;
  parrot?: string; // pole opcjonalne: papugę ma nie każdy pirat
}

interface CrewCardProps {
  member: CrewMember;
}

const crew: CrewMember[] = [
  { name: "Anne Bonny", role: "kapitan", level: 10, parrot: "Kapitan Pióro" },
  { name: "Jack Rackham", role: "sternik", level: 7 },
  { name: "Mary Read", role: "kucharz", level: 5 },
  // Spróbuj: dopisz bosmana z papugą, na przykład { name: "Israel Hands", role: "bosman", level: 6, parrot: "Szkwał" }
];

function CrewCard({ member }: CrewCardProps) {
  return (
    <article style={{ background: "#111827", color: "white", padding: 16, borderRadius: 8, border: "1px solid #eab308" }}>
      <h3 style={{ margin: "0 0 8px" }}>{member.name}</h3>
      <p style={{ margin: 0, color: "#d1d5db" }}>
        {member.role}, poziom {member.level}
      </p>
      {member.parrot && (
        <p style={{ margin: "8px 0 0", color: "#facc15" }}>Papuga: {member.parrot}</p>
      )}
    </article>
  );
}

export default function App() {
  return (
    <main style={{ minHeight: "100vh", background: "black", padding: 32, fontFamily: "system-ui, sans-serif" }}>
      <h1 style={{ color: "#dc2626", textAlign: "center", marginTop: 0 }}>Załoga</h1>
      <div style={{ display: "grid", gap: 16, gridTemplateColumns: "repeat(auto-fit, minmax(200px, 1fr))" }}>
        {crew.map((member) => (
          <CrewCard key={member.name} member={member} />
        ))}
      </div>
    </main>
  );
}

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. Czym jest TypeScript?

  2. 2. Do czego służy interface w TypeScript?

  3. 3. Claude naprawił błąd typów, dopisując as any, i npx tsc --noEmit przechodzi. Co robisz?

Zadania praktyczne w grze

  • Układanie w poziomie

    Ułóż zapis typowanej zmiennej tekstowej w TypeScript (od lewej do prawej):

  • Klikanie w kolejności

    Zbuduj opcjonalne pole 'parrot' typu string w interfejsie CrewMember:

  1. PytanieQuiz: Czym jest TypeScript
  2. Ułóż w kolejnościSortowanie: Typowana zmienna w TypeScript
  3. PytanieQuiz: Interface w TypeScript
  4. Kliknij w kolejnościSortowanie: Opcjonalne pole w interfejsie
  5. PytanieQuiz: Claude wycisza błąd typów

Przydatne artykuły