Kurs vibe coding z Claude Code · Moduł 4: Klon Instagrama
Szkielet okrętu: stany ładowania i szkielet galerii
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ę.
Problem: martwy link i pusty ekran
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ź:
- 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. - Błąd naprawdę się pokazuje. Poproś Claude o chwilowe
throw new Error("Sztorm")na początkugetPhotos, 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. retry, a niereset. To typowy błąd agenta. Starsze wersje Next.js dawały plikowi błędu tylko funkcjęreseti 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.
- Szkielet tylko w trybie deweloperskim. Uruchom
npm run buildi 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. Ponpm run startszkieletu nie zobaczysz, a nowe zdjęcia z bazy pojawiłyby się dopiero po kolejnym buildzie. Wnpm run devstrona 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. Co robi klasa animate-pulse na szarych kafelkach szkieletu galerii?
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: