Kurs vibe coding z Claude Code · Moduł 4: Klon Instagrama

Szkielet okrętu: stany ładowania i szkielet galerii

9 min czytania ·
W tej lekcji8

Zdjęcia galerii leżą na razie w pliku lib/photos.ts więc strona ma je pod ręką w chwili, w której powstaje. Prawdziwa galeria pobiera je z bazy albo z innego serwera, a to trwa. W tej lekcji udasz wolny serwer, a Claude Code zbuduje na czas czekania szkielet galerii i dopisze dwa stany, o których agenci lubią zapominać: błąd i pustą skrzynię.

Strona, która czeka na dane, nie ma czego pokazać. Odświeżona w przeglądarce długo stoi bez odpowiedzi, a po kliknięciu linku z innej strony wygląda, jakby kliknięcie nie zadziałało. Dokumentacja Next.js ostrzega, że użytkownik ma wtedy wrażenie, że aplikacja nie odpowiada. Załoga klika drugi raz, odświeża i zaczyna czekanie od nowa.

Lekarstwem jest stan ładowania, czyli osobny wygląd strony na czas czekania. Najlepiej taki, który ma kształt przyszłej treści. Szary zarys kafelków w miejscu zdjęć nazywa się szkieletem (ang. skeleton): widać, co się pojawi i gdzie, więc nic nie podskakuje, gdy dane w końcu przyjdą. To jak zarys okrętu w stoczni: masztu jeszcze nie ma, ale wiadomo, gdzie stanie.

Polecenie dla Claude Code: wolny serwer i loading.tsx

Pierwszy krok dotyka czterech plików, ale każdy jest prosty, więc obejdzie się bez planu. Polecenie mówi, gdzie ma powstać opóźnienie, czego nie używać i jaki kształt ma mieć szkielet:

Polecenie dla Claude Code:

W @lib/photos.ts dodaj funkcję async getPhotos(), która czeka 1,5 s
i zwraca zdjęcia. To udawany wolny serwer na czas nauki, opisz to
komentarzem. Strona @app/gallery/page.tsx ma czekać na getPhotos()
na serwerze, bez "use client" i bez useEffect. Na czas czekania dodaj
app/gallery/loading.tsx: szare koło w miejscu awatara, pasek w miejscu
tytułu i siatkę szarych kafelków z animate-pulse w osobnym pliku
components/GallerySkeleton.tsx, z tymi samymi kolumnami i odstępem co
siatka w @components/Gallery.tsx. Na koniec npm run build i npm run lint.

Zakaz useEffect ma powód. W lekcji 2_3 efekt działał w przeglądarce, ale strona w App Routerze jest domyślnie Server Component i może sama poczekać na dane na serwerze, zanim wyśle HTML. Starsze poradniki pobierają dane w efekcie komponentu klienckiego i Claude czasem idzie tą drogą z przyzwyczajenia. Strona nie czeka wtedy na nic, więc szkielet z loading.tsx w ogóle się nie pokaże.

Co napisał Claude: udawany serwer

Otwórz w Cursorze lib/photos.ts. Pod tablicą zdjęć stoi nowa funkcja:

// Na czas nauki udajemy wolny serwer: 1,5 s czekania.
// Gdy zdjęcia trafią do bazy, zostanie samo zapytanie.
export async function getPhotos(): Promise<Photo[]> {
  await new Promise((resolve) => setTimeout(resolve, 1500));
  return photos;
}

async przed funkcją znaczy, że zwraca ona obietnicę (Promise), czyli wynik, który przyjdzie później. await każe na tę obietnicę poczekać, a new Promise z setTimeout to po prostu przerwa na 1500 milisekund. Tablica photos się nie zmieniła, tylko trzeba na nią poczekać, jak na odpowiedź prawdziwego serwera.

W app/gallery/page.tsx zmienił się początek komponentu:

export default async function GalleryPage() {
  const photos = await getPhotos();

Komponent strony stał się funkcją async i czeka na zdjęcia, zanim cokolwiek zwróci. Tak może tylko Server Component: nie ma tu "use client", stanu ani efektów. Nagłówek i siatka pod spodem zostały takie jak w lekcji 3_3.

Co napisał Claude: szkielet i loading.tsx

Otwórz components/GallerySkeleton.tsx. To lista szarych kafelków w tej samej siatce co zdjęcia:

export default function GallerySkeleton() {
  return (
    <div role="status">
      <span className="sr-only">Ładuję zdjęcia z rejsu…</span>
      <ul
        aria-hidden="true"
        className="grid grid-cols-1 gap-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4"
      >
        {Array.from({ length: 8 }, (_, index) => (
          <li key={index} className="aspect-square animate-pulse bg-gray-200" />
        ))}
      </ul>
    </div>
  );
}

Array.from({ length: 8 }, ...) tworzy osiem kafelków, a klasy siatki są te same co w Gallery.tsx, więc szkielet ma tyle kolumn co galeria na każdym ekranie. aspect-square robi kwadraty, bg-gray-200 daje szary kolor, a animate-pulse raz po raz przygasza kafelek i rozjaśnia go z powrotem. Klucz z indeksu jest tu w porządku, choć w lekcji 2_8 go unikałeś: lista szarych kafelków nigdy się nie zmienia ani nie przestawia.

Szare kafelki nic nie mówią osobie, której czytnik ekranu czyta stronę na głos, więc aria-hidden="true" je przed nim chowa. Zamiast nich czytnik odczyta zdanie z klasą sr-only, niewidoczne na ekranie, a role="status" każe mu je ogłosić.

Szkielet całej strony stoi w app/gallery/loading.tsx:

import GallerySkeleton from "@/components/GallerySkeleton";

export default function Loading() {
  return (
    <main className="mx-auto max-w-4xl p-4">
      <div className="mb-6 flex items-center gap-4">
        <div className="h-24 w-24 animate-pulse rounded-full bg-gray-200" />
        <div className="h-8 w-48 animate-pulse rounded bg-gray-200" />
      </div>
      <GallerySkeleton />
    </main>
  );
}

loading.tsx to plik specjalny Next.js, tak jak page.tsx. Nikt go nie importuje: Next.js sam owija nim stronę z tego samego folderu i pokazuje go, dopóki strona czeka. Według dokumentacji robi to przez <Suspense>, komponent Reacta, do którego zaraz wrócisz. Odśwież localhost:3000/gallery: przez półtorej sekundy pulsują szare koło, pasek i kafelki, a potem pojawia się galeria.

Cztery stany i Suspense bliżej danych

Gdy przyjrzysz się szkieletowi, zobaczysz marnotrawstwo: awatar i tytuł znasz od początku, a też czekają. loading.tsx zasłania całą stronę naraz. Węższą zasłonę daje sam <Suspense>: otaczasz nim tylko tę część, która czeka na dane, a w propsie fallback podajesz, co pokazać w zastępstwie. Dokumentacja Next.js zaleca właśnie <Suspense> blisko miejsca, które czeka na dane.

To też dobra chwila na resztę stanów. Każdy widok z danymi ma ich cztery: ładowanie, błąd, pusto i sukces. Claude zapytany o "listę zdjęć" zrobi pewnie pierwszy i ostatni, a środkowe pominie, bo nikt o nie nie prosił. Dlatego polecenie wymienia wszystkie cztery:

Polecenie dla Claude Code:

/plan Nagłówek profilu nie potrzebuje zdjęć, więc niech stoi od razu.
Przenieś czekanie na getPhotos() do nowego Server Component
components/PhotoGrid.tsx i owiń go w @app/gallery/page.tsx w Suspense
z GallerySkeleton. Obsłuż cztery stany: ładowanie (szkielet), pusta
lista (zachęta do dodania pierwszego zdjęcia), błąd (app/gallery/error.tsx
z przyciskiem Spróbuj ponownie, według dokumentacji Next.js
z node_modules/next/dist/docs) i sukces. @components/Gallery.tsx zostaje
bez zmian. Każdy krok kończ npm run build i npm run lint.

Odesłanie do dokumentacji w node_modules ma powód. Plik AGENTS.md z kreatora ostrzega Claude, że ta wersja Next.js ma zmiany, których nie zna z danych treningowych, a plik błędu zmienił się niedawno. W planie szukaj czterech plików z polecenia. Jeśli Claude zacznie przerabiać Gallery.tsx na Server Component, naciśnij Esc: polubienia z lekcji 3_3 potrzebują stanu, a stan żyje tylko w komponencie klienckim.

Co napisał Claude: Suspense, pusto i błąd

Otwórz app/gallery/page.tsx. Strona nie czeka już na nic, a pod nagłówkiem stoi:

<Suspense fallback={<GallerySkeleton />}>
  <PhotoGrid />
</Suspense>

Serwer wysyła od razu nagłówek i szkielet z fallback, a gdy PhotoGrid skończy czekać, dosyła gotową siatkę w to samo miejsce. Takie wysyłanie strony w kawałkach nazywa się streamingiem. loading.tsx może zostać: zasłoni całą stronę, gdyby kiedyś znowu musiała czekać w całości.

Czekanie przeniosło się do components/PhotoGrid.tsx:

export default async function PhotoGrid() {
  const photos = await getPhotos();

  if (photos.length === 0) {
    return (
      <p className="py-12 text-center text-gray-600">
        Skrzynia jest jeszcze pusta. Dodaj pierwsze zdjęcie z rejsu.
      </p>
    );
  }

  return <Gallery photos={photos} />;
}

To serwerowy komponent async, jak strona w pierwszym kroku. Pusty stan sprawdza dopiero po await, więc nigdy nie pomyli go z ładowaniem. Gdy zdjęcia są, oddaje je komponentowi Gallery, a polubienia i okno działają jak w lekcji 3_3.

Ostatni stan mieszka w app/gallery/error.tsx:

"use client";

export default function GalleryError({
  retry,
}: {
  error: unknown;
  retry: () => void;
}) {
  return (
    <main className="mx-auto max-w-4xl p-4 text-center">
      <h2 className="text-xl font-bold">Sztorm zatrzymał zdjęcia</h2>
      <p className="my-2 text-gray-600">Nie udało się pobrać galerii.</p>
      <button
        type="button"
        onClick={() => retry()}
        className="rounded bg-gray-900 px-4 py-2 text-white"
      >
        Spróbuj ponownie
      </button>
    </main>
  );
}

Gdy coś w trasie /gallery rzuci błąd, Next.js pokaże ten komponent zamiast strony, razem z nagłówkiem, bo error.tsx obejmuje cały folder trasy. Według dokumentacji plik błędu musi być komponentem klienckim, stąd "use client". retry() pobiera dane i rysuje stronę od nowa: jeśli sztorm minął, galeria wraca na miejsce.

Przegląd kapitana

Uruchom npm run dev i sprawdź:

  1. Szkielet ma kształt galerii. Odśwież stronę i zwężaj okno w trakcie ładowania: szare kafelki układają się w cztery, trzy, dwie i jedną kolumnę, tak jak potem zdjęcia. Gdy szkielet ma inne klasy siatki niż Gallery.tsx, strona podskoczy w chwili, w której przyjdą dane.
  2. Błąd naprawdę się pokazuje. Poproś Claude o chwilowe throw new Error("Sztorm") na początku getPhotos, odśwież stronę i obejrzyj komunikat. W trybie deweloperskim Next.js dorzuci w rogu znaczek z błędem; to podpowiedź dla Ciebie, załoga jej nie zobaczy. Potem cofnij zmianę przez /rewind.
  3. retry, a nie reset. To typowy błąd agenta. Starsze wersje Next.js dawały plikowi błędu tylko funkcję reset i Claude często pisze ją z pamięci:
export default function GalleryError({
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {

TypeScript i lint przechodzą, komunikat się pokazuje, przycisk wygląda na działający. Dokumentacja mówi jednak, że reset tylko czyści błąd i rysuje stronę od nowa, bez ponownego pobrania danych. Sprawdziliśmy to: po minionym sztormie przycisk z reset dalej pokazywał komunikat, a ten z retry przywracał galerię. W diffie szukaj słowa retry.

  1. Szkielet tylko w trybie deweloperskim. Uruchom npm run build i znajdź w wyniku linię /gallery. Stoi przy niej kółko ○, które legenda opisuje jako "prerendered as static content": strona powstała raz, w czasie builda, i półtorej sekundy czekania minęło wtedy, na Twoim komputerze. Po npm run start szkieletu nie zobaczysz, a nowe zdjęcia z bazy pojawiłyby się dopiero po kolejnym buildzie. W npm run dev strona powstaje przy każdym wejściu, dlatego tam szkielet widać. Wyszukiwarka z następnej lekcji to zmieni.

Następny krok

Gdy przegląd przejdzie, poproś o commit, na przykład "Galeria: szkielet, pusty stan i strona błędu". Potem małe rozszerzenie strony błędu:

W @app/gallery/error.tsx zapisz błąd w konsoli przeglądarki przez
useEffect z console.error, tak jak w przykładzie z dokumentacji
Next.js. Nic poza tym plikiem nie zmieniaj.

Sprawdzisz to kolejnym chwilowym sztormem: w konsoli przeglądarki pojawi się wpis z komunikatem. W wersji produkcyjnej będzie w nim jednak tylko ogólny komunikat z identyfikatorem digest. Dokumentacja tłumaczy, że Next.js ukrywa szczegóły błędów z serwera, żeby nie zdradzić niczego wrażliwego; pełną treść znajdziesz w logach serwera po tym identyfikatorze.

W edytorze poniżej przełączasz cztery stany galerii i odtwarzasz półtorej sekundy ładowania. Zobacz, że szkielet i zdjęcia zajmują to samo miejsce, a potem rozwiąż zadania.

Zapamiętaj: szkielet to zarys okrętu w stoczni, a kapitan zamawia u Claude Code wszystkie cztery stany, bo załoga zobaczy każdy z nich.

Kod do tej lekcji: App.jsx
// Cztery stany galerii: ładowanie, błąd, pusto i sukces
// W projekcie stany dają loading.tsx, Suspense, error.tsx i PhotoGrid.
// Tu przełączasz je przyciskami, żeby porównać, co widzi załoga.
import { useState } from 'react';

const photos = [
  {
    id: 'zachod-na-plazy',
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600',
    alt: 'Fale na piaszczystej plaży o zachodzie słońca',
  },
  {
    id: 'fale-z-gory',
    src: 'https://images.unsplash.com/photo-1505118380757-91f5f5632de0?w=600',
    alt: 'Turkusowe fale przy białej plaży widziane z lotu ptaka',
  },
  {
    id: 'zaglowka-noca',
    src: 'https://images.unsplash.com/photo-1534447677768-be436bb09401?w=600',
    alt: 'Mała żaglówka na spokojnym morzu pod rozgwieżdżonym niebem',
  },
  {
    id: 'palmy',
    src: 'https://images.unsplash.com/photo-1519046904884-53103b34b206?w=600',
    alt: 'Palmy i słomkowy parasol na białej plaży',
  },
  {
    id: 'szlak',
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=600',
    alt: 'Droga między czerwonymi skałami prowadząca w stronę góry',
  },
  {
    id: 'rafa',
    src: 'https://images.unsplash.com/photo-1544551763-46a013bb70d5?w=600',
    alt: 'Nurek wśród ławicy żółtych ryb przy rafie',
  },
];

// Ta sama siatka w szkielecie i w galerii: nic nie podskakuje
const gridClasses = 'grid grid-cols-2 gap-1 sm:grid-cols-3';

function GallerySkeleton() {
  return (
    <div role="status">
      <span className="sr-only">Ładuję zdjęcia z rejsu…</span>
      <ul aria-hidden="true" className={gridClasses}>
        {Array.from({ length: 6 }, (_, index) => (
          <li key={index} className="aspect-square animate-pulse bg-gray-200" />
        ))}
      </ul>
    </div>
  );
}

function PhotoGrid({ items }) {
  return (
    <ul className={gridClasses}>
      {items.map((photo) => (
        <li key={photo.id} className="relative aspect-square bg-slate-800">
          <img
            src={photo.src}
            alt={photo.alt}
            className="absolute inset-0 h-full w-full object-cover"
          />
        </li>
      ))}
    </ul>
  );
}

const views = [
  ['loading', 'Ładowanie'],
  ['error', 'Błąd'],
  ['empty', 'Pusto'],
  ['success', 'Sukces'],
];

export default function App() {
  const [view, setView] = useState('success');

  // Udajemy wolny serwer: półtorej sekundy szkieletu, potem zdjęcia
  const replay = () => {
    setView('loading');
    setTimeout(() => setView('success'), 1500);
  };

  return (
    <div className="min-h-screen bg-slate-100 p-4 text-slate-900">
      <h1 className="mb-1 text-2xl font-bold">Treasure Gallery</h1>
      <p className="mb-3 text-sm text-slate-600">Zdjęcia z rejsu</p>

      <div className="mb-4 flex flex-wrap gap-2">
        {views.map(([id, label]) => (
          <button
            key={id}
            type="button"
            onClick={() => setView(id)}
            aria-pressed={view === id}
            className={view === id
              ? 'rounded bg-slate-900 px-3 py-1 text-sm text-white'
              : 'rounded bg-white px-3 py-1 text-sm'}
          >
            {label}
          </button>
        ))}
        <button
          type="button"
          onClick={replay}
          className="rounded bg-amber-500 px-3 py-1 text-sm font-semibold text-slate-900"
        >
          Odtwórz ładowanie 1,5 s
        </button>
      </div>

      {view === 'loading' && <GallerySkeleton />}

      {view === 'error' && (
        <div className="py-8 text-center">
          <h2 className="text-xl font-bold">Sztorm zatrzymał zdjęcia</h2>
          <p className="my-2 text-slate-600">Nie udało się pobrać galerii.</p>
          <button
            type="button"
            onClick={replay}
            className="rounded bg-slate-900 px-4 py-2 text-white"
          >
            Spróbuj ponownie
          </button>
        </div>
      )}

      {view === 'empty' && (
        <p className="py-12 text-center text-slate-600">
          Skrzynia jest jeszcze pusta. Dodaj pierwsze zdjęcie z rejsu.
        </p>
      )}

      {view === 'success' && <PhotoGrid items={photos} />}
    </div>
  );
}

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. Co robi klasa animate-pulse na szarych kafelkach szkieletu galerii?

  2. 2. Przycisk Spróbuj ponownie w error.tsx tylko czyści błąd i rysuje stronę od nowa, bez ponownego pobrania zdjęć. Co zobaczysz po kliknięciu, gdy sztorm już minął?

To 2 z 5 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj, co się dzieje po wejściu na /gallery, gdy siatka czeka w Suspense:

  • Klikanie w kolejności

    Kliknij fragmenty w kolejności, aby strona poczekała na zdjęcia na serwerze:

  1. PytanieQuiz: animate-pulse w szkielecie
  2. Ułóż w kolejnościSortowanie: Ładowanie galerii krok po kroku
  3. PytanieQuiz: Przycisk, który nie pobiera danych
  4. PytanieQuiz: Pusty stan galerii
  5. Kliknij w kolejnościKlikanie: Strona czeka na zdjęcia
  6. PytanieQuiz: loading.tsx a Suspense
  7. PytanieQuiz: Szkielet po buildzie

Przydatne artykuły