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

Cisza na pokładzie: wyszukiwarka z debounce

8 min czytania ·
W tej lekcji8

Galeria rośnie z każdym rejsem i coraz trudniej znaleźć w niej jedno zdjęcie. Czas na wyszukiwarkę po podpisach. Szukać będzie serwer, bo gdy zdjęcia trafią do bazy, przeglądarka nie dostanie ich wszystkich naraz. A każde pytanie do serwera kosztuje: u nas półtorej sekundy z lekcji 3_4.

Problem: sześć pytań na jedno słowo

Kapitan wpisuje "wachta". Pole zmienia się sześć razy: "w", "wa", "wac" i tak dalej. Jeśli każda zmiana wysyła pytanie do serwera, serwer szuka sześć razy, pięć wyników nie jest nikomu potrzebnych, a szkielet miga przy każdej literze.

Rozwiązaniem jest debouncing: z wysłaniem pytania czekasz, aż piszący zrobi przerwę. Każda nowa litera kasuje odliczanie i zaczyna je od zera, więc pytanie wychodzi dopiero po 300 milisekundach ciszy. Jak sternik, który nie kręci kołem przy każdym podmuchu, tylko czeka, aż wiatr się ustali.

Fraza trafi też do adresu strony, jako ?q=wachta. Taki fragment adresu po znaku zapytania to parametr wyszukiwania (search param). Dzięki niemu link do wyników da się wysłać załodze, a strona po odświeżeniu pamięta, czego szukałeś.

Polecenie dla Claude Code

Polecenie mówi, kto szuka, gdzie stoi pole, ile trwa cisza i czego nie robić:

Polecenie dla Claude Code:

Dodaj do Treasure Gallery wyszukiwarkę po podpisach zdjęć. Fraza
trafia do adresu jako ?q=, a filtruje serwer: getPhotos(query)
w @lib/photos.ts, bez względu na wielkość liter. Pole stoi nad siatką
w nowym Client Component components/SearchBox.tsx i zmienia adres przez
router.replace dopiero po 300 ms bez pisania (debounce). Bez nowych
paczek i bez setState w useEffect. Pusta fraza usuwa q z adresu. Gdy nic
nie pasuje, napisz, że żadne zdjęcie nie ma takiego podpisu. Nie dodawaj
memo, useMemo ani useCallback. Na koniec npm run build i npm run lint.

Zakazy mają powody. Nowa paczka do debounce to cudzy kod w projekcie dla kilku linii. Ustawianie stanu wprost w efekcie łamie regułę react-hooks/set-state-in-effect i npm run lint je odrzuci. Zresztą efekt nie jest tu potrzebny: pytanie wysyła się dlatego, że ktoś pisze, a reakcja na zdarzenie należy do funkcji obsługi zdarzenia. O memoizacji przeczytasz pod koniec lekcji.

Co napisał Claude: serwer szuka

Otwórz w Cursorze lib/photos.ts. Funkcja z lekcji 3_4 dostała parametr:

export async function getPhotos(query = ""): Promise<Photo[]> {
  await new Promise((resolve) => setTimeout(resolve, 1500));
  const phrase = query.trim().toLocaleLowerCase("pl");
  return photos.filter((photo) =>
    photo.caption.toLocaleLowerCase("pl").includes(phrase),
  );
}

query = "" to wartość domyślna, więc wywołanie bez frazy działa jak wcześniej. toLocaleLowerCase("pl") zamienia litery na małe według polskich zasad i "SKRZYNIĘ" znajdzie "skrzynię". filter zostawia zdjęcia, których podpis zawiera frazę, a pusta fraza pasuje do każdego podpisu. Opóźnienie zostało: to nasz udawany koszt każdego pytania.

Strona app/gallery/page.tsx czyta frazę z adresu:

export default async function GalleryPage({ searchParams }: PageProps<"/gallery">) {
  const { q } = await searchParams;
  const query = typeof q === "string" ? q : "";

searchParams to parametry z adresu, które Next.js podaje stronie jako obietnicę, dlatego stoi przed nimi await. PageProps<"/gallery"> to typ, który Next.js sam generuje dla tej trasy, bez importu. Parametr może przyjść jako tekst, jako lista albo wcale, więc typeof q === "string" zostawia tylko tekst, a resztę zamienia na pustą frazę.

Pod nagłówkiem stoją pole i siatka:

<SearchBox initialQuery={query} />

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

PhotoGrid przekazuje frazę do getPhotos, a przy pustym wyniku z frazą pisze, że żadne zdjęcie nie ma takiego podpisu, zamiast zachęcać do dodania pierwszego. Nowy jest key={query}. Każda fraza to dla Reacta nowa granica Suspense, więc przy każdym wyszukiwaniu wraca szkielet, a Gallery startuje od nowa ze świeżymi zdjęciami. Dlaczego to ważne, zobaczysz w przeglądzie.

Co napisał Claude: pole z debounce

Otwórz components/SearchBox.tsx. Plik zaczyna się od "use client", bo pole reaguje na pisanie. Odliczanie trzyma useRef z lekcji 2_5, a funkcja obsługi zdarzenia je przestawia:

const timer = useRef<ReturnType<typeof setTimeout> | null>(null);

const handleChange = (value: string) => {
  if (timer.current) clearTimeout(timer.current);
  timer.current = setTimeout(() => {
    const phrase = value.trim();
    router.replace(phrase ? `${pathname}?q=${encodeURIComponent(phrase)}` : pathname);
  }, 300);
};

Każda litera najpierw kasuje poprzednie odliczanie przez clearTimeout, a potem nastawia nowe. Dopiero 300 milisekund ciszy przepuszcza frazę do router.replace, który zmienia adres bez nowego wpisu w historii przeglądarki, więc przycisk Wstecz nie cofa po literze. router i pathname (obecna ścieżka, tu /gallery) dają hooki useRouter i usePathname z next/navigation. encodeURIComponent zamienia spacje, polskie litery i znaki & na bezpieczny zapis w adresie. Ref, a nie zwykła zmienna let, bo ref przetrwa kolejne rendery; zwykłą zmienną odrzuci już npm run lint regułą react-hooks/immutability.

Pod funkcją stoi jedyny efekt w pliku:

useEffect(() => {
  return () => {
    if (timer.current) clearTimeout(timer.current);
  };
}, []);

Nie ustawia żadnego stanu, tylko sprząta. Gdy ktoś wpisze literę i od razu przejdzie na inną stronę, odliczanie bez sprzątania tyka dalej i po 300 milisekundach wciąga go z powrotem do galerii; sprawdziliśmy to. Sprzątanie przy odmontowaniu kasuje odliczanie razem z komponentem. Samo pole ma defaultValue={initialQuery}, czyli startuje z frazą z adresu, i onChange wołające handleChange.

Przegląd kapitana

Uruchom npm run dev, otwórz localhost:3000/gallery i sprawdź:

  1. Jedno pytanie na jedno słowo. Dowodem jest terminal z npm run dev: Next.js wypisuje tam każde zapytanie do strony. Wpisz "wachta" w zwykłym tempie i policz nowe linie. Ma być jedna, GET /gallery?q=wachta 200. Gdy Claude pominie clearTimeout, debounce tylko opóźnia pytania i zobaczysz sześć:
GET /gallery?q=w 200 in 1529ms (next.js: 1.8ms, application-code: 1527ms)
GET /gallery?q=wa 200 in 1519ms (next.js: 2ms, application-code: 1517ms)
GET /gallery?q=wac 200 in 1520ms (next.js: 8ms, application-code: 1512ms)
GET /gallery?q=wach 200 in 1521ms (next.js: 1.7ms, application-code: 1519ms)
GET /gallery?q=wacht 200 in 1517ms (next.js: 1.2ms, application-code: 1516ms)
GET /gallery?q=wachta 200 in 1511ms (next.js: 2ms, application-code: 1509ms)

Build i lint przechodzą w obu wersjach, więc licz linie, a nie wierz zapewnieniu "debounce działa".

  1. key na Suspense. To typowy błąd agenta: granica bez klucza. Sprawdziliśmy, co się wtedy dzieje. Przy pisaniu szkielet się nie pokazuje, bo przy zmianie adresu React zostawia na ekranie stare wyniki, a gdy serwer odpowie, siatka dalej ma wszystkie sześć zdjęć. Gallery wzięła zdjęcia do stanu przez useState(photos), a wartość startowa liczy się tylko przy pierwszym renderze. Po odświeżeniu strony wynik jest poprawny, przy pisaniu nie, i to myli najbardziej. W diffie szukaj key={query}.
  2. Polskie litery i pusty wynik. Wpisz "SKRZYNIĘ" wielkimi literami: ma się znaleźć zdjęcie z podpisem "Tu zakopaliśmy skrzynię". Wpisz "kraken": ma się pojawić zdanie, że żadne zdjęcie nie ma takiego podpisu, a nie zachęta do dodania pierwszego zdjęcia.
  3. Link do wyników. Skopiuj adres z ?q= do nowej karty: wyniki i fraza w polu są te same. Wyczyść pole: adres traci ?q=.

Na koniec znajdź w wyniku npm run build linię /gallery. Stoi przy niej teraz ƒ (Dynamic): strona korzysta z parametrów adresu, więc powstaje przy każdym wejściu, a szkielet z lekcji 3_4 widać także po buildzie.

Debounce czy useDeferredValue

Debounce oszczędza serwer. Gdy filtrujesz zdjęcia, które przeglądarka już ma, dokumentacja Reacta poleca coś innego: useDeferredValue. Hook zwraca opóźnioną kopię wartości, a React rysuje listę dla nowej frazy w tle i przerywa tę pracę, gdy przyjdzie kolejna litera:

const [query, setQuery] = useState("");
const deferredQuery = useDeferredValue(query);
const phrase = deferredQuery.trim().toLocaleLowerCase("pl");
const visible = items.filter((photo) =>
  photo.caption.toLocaleLowerCase("pl").includes(phrase),
);

Pole pokazuje query od razu, a lista korzysta z deferredQuery. Nie ma tu żadnej stałej liczby milisekund: na szybkim komputerze opóźnienie jest niezauważalne, na wolnym lista zostaje trochę w tyle za polem. Dokumentacja podkreśla też, że useDeferredValue sam nie zmniejsza liczby zapytań do sieci. Stąd prosta zasada: pytasz serwer, to debounce; rysujesz w przeglądarce, to useDeferredValue. Obie techniki da się łączyć.

Memo na zapas

Polecenie zabraniało trzech narzędzi, które Claude lubi dodać "dla wydajności". React.memo pomija ponowne rysowanie komponentu, gdy jego propsy się nie zmieniły. useMemo zapamiętuje wynik obliczenia, a useCallback zapamiętuje samą funkcję, żeby przy kolejnym renderze była tą samą funkcją. Każde z nich dokłada kod i zależności do pilnowania, a przy sześciu zdjęciach nic nie przyspiesza. Polecam zasadę: najpierw zmierz, na przykład w zakładce Profiler w React DevTools, potem optymalizuj. Jeśli Claude doda którekolwiek z nich bez pomiaru, zapytaj, co zmierzył.

Następny krok

Zanim zrobisz commit, uruchom /code-review z lekcji 2_9 i przeczytaj raport w Cursorze. Potem commit, na przykład "Galeria: wyszukiwarka po podpisach z debounce", i małe rozszerzenie:

W @components/PhotoGrid.tsx nad siatką pokaż, ile zdjęć pasuje do
frazy, z poprawną polską odmianą: 1 zdjęcie, 2 zdjęcia, 5 zdjęć. Tylko
gdy fraza nie jest pusta. Niczego poza tym plikiem nie zmieniaj.

W diffie sprawdź, co funkcja odmiany zwróci dla 12 i 22: poprawnie jest "12 zdjęć" i "22 zdjęcia". Na tych liczbach potyka się wiele prostych warunków z if.

W edytorze poniżej przełączasz debounce i liczysz pytania do udawanego serwera: wpisz "wachta" z debounce i bez niego, a potem porównaj licznik.

Pamiętaj: sternik czeka, aż wiatr się ustali, a kapitan nie wierzy w "powinno działać", tylko liczy linie w dzienniku serwera.

Kod do tej lekcji: App.jsx
// Wyszukiwarka z debounce: ile pytań leci do serwera?
// Serwer jest udawany: czeka 600 ms i filtruje zdjęcia po podpisie.
import { useEffect, useRef, 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',
    caption: 'Tu zakopaliśmy skrzynię',
  },
  {
    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',
    caption: 'Zatoka z bocianiego gniazda',
  },
  {
    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',
    caption: 'Nocna wachta',
  },
  {
    id: 'palmy',
    src: 'https://images.unsplash.com/photo-1519046904884-53103b34b206?w=600',
    alt: 'Palmy i słomkowy parasol na białej plaży',
    caption: 'Wyspa z mapy',
  },
  {
    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',
    caption: 'Szlak do kryjówki',
  },
  {
    id: 'rafa',
    src: 'https://images.unsplash.com/photo-1544551763-46a013bb70d5?w=600',
    alt: 'Nurek wśród ławicy żółtych ryb przy rafie',
    caption: 'Nurkowanie przy rafie',
  },
];

function fakeServer(query) {
  return new Promise((resolve) => {
    setTimeout(() => {
      const phrase = query.trim().toLocaleLowerCase('pl');
      resolve(
        photos.filter((photo) =>
          photo.caption.toLocaleLowerCase('pl').includes(phrase),
        ),
      );
    }, 600);
  });
}

export default function App() {
  const [debounce, setDebounce] = useState(true);
  const [requests, setRequests] = useState([]);
  const [results, setResults] = useState(photos);
  const timer = useRef(null);

  const send = async (value) => {
    setRequests((prev) => [...prev, value.trim() || '(pusta fraza)']);
    const found = await fakeServer(value);
    setResults(found);
  };

  const handleChange = (value) => {
    if (!debounce) {
      send(value);
      return;
    }
    // Każda litera kasuje poprzednie odliczanie i nastawia nowe
    if (timer.current) clearTimeout(timer.current);
    timer.current = setTimeout(() => send(value), 300);
  };

  // Sprzątanie: odliczanie nie przeżyje zniknięcia komponentu
  useEffect(() => {
    return () => {
      if (timer.current) clearTimeout(timer.current);
    };
  }, []);

  return (
    <div className="min-h-screen bg-slate-100 p-4 text-slate-900">
      <h1 className="mb-3 text-2xl font-bold">Treasure Gallery</h1>

      <label className="mb-2 flex items-center gap-2 text-sm">
        <input
          type="checkbox"
          checked={debounce}
          onChange={(event) => setDebounce(event.target.checked)}
        />
        Debounce 300 ms
      </label>

      <input
        type="search"
        onChange={(event) => handleChange(event.target.value)}
        placeholder="Szukaj w podpisach..."
        aria-label="Szukaj w podpisach zdjęć"
        className="mb-3 w-full rounded border border-slate-300 bg-white px-3 py-2"
      />

      <div className="mb-3 rounded bg-white p-3 text-sm">
        <div className="mb-1 flex items-center justify-between">
          <span className="font-semibold">Pytania do serwera: {requests.length}</span>
          <button
            type="button"
            onClick={() => setRequests([])}
            className="rounded bg-slate-200 px-2 py-1 text-xs"
          >
            Wyzeruj licznik
          </button>
        </div>
        <ol className="list-decimal pl-5 text-slate-600">
          {requests.map((phrase, index) => (
            <li key={index}>{phrase}</li>
          ))}
        </ol>
      </div>

      {results.length === 0 ? (
        <p className="py-8 text-center text-slate-600">
          Żadne zdjęcie nie ma takiego podpisu.
        </p>
      ) : (
        <ul className="grid grid-cols-2 gap-1 sm:grid-cols-3">
          {results.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"
              />
              <span className="absolute inset-x-0 bottom-0 bg-black/60 px-2 py-1 text-xs text-white">
                {photo.caption}
              </span>
            </li>
          ))}
        </ul>
      )}
    </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. Czym jest debouncing w polu wyszukiwania?

  2. 2. Po wpisaniu słowa „wachta” terminal z npm run dev pokazuje sześć linii: GET /gallery?q=w, ?q=wa i tak dalej aż do ?q=wachta. Czego najpewniej brakuje w handleChange?

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

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj linie funkcji handleChange z debounce (od góry do dołu):

  • Klikanie w kolejności

    Kliknij fragmenty w kolejności, aby odczytać parametr q z adresu strony:

  1. PytanieQuiz: Debouncing
  2. Ułóż w kolejnościSortowanie: Debounce w funkcji obsługi zdarzenia
  3. PytanieQuiz: Sześć linii w terminalu
  4. Kliknij w kolejnościKlikanie: Fraza z adresu
  5. PytanieQuiz: key na Suspense
  6. PytanieQuiz: Filtrowanie w przeglądarce
  7. PytanieQuiz: useMemo a useCallback

Przydatne artykuły