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

Claude Code zakłada projekt Next.js

10 min czytania ·
W tej lekcji12

Silnik działa czas zwodować okręt. W tej lekcji Claude Code założy projekt strony gry "Kraken's Call", a Ty przeczytasz w Cursorze wszystko, co powstało, i zażądasz dowodu, że projekt się buduje.

Problem: kreator pyta o dwanaście rzeczy

Nowy projekt Next.js zakłada kreator create-next-app. Uruchomiony bez flag zadaje pytania jedno po drugim: o nazwę, o ustawienia zalecane, a po wybraniu własnych ustawień o dziesięć kolejnych rzeczy, od TypeScriptu po pliki dla agentów. Każde czeka na odpowiedź z klawiatury. Drugie wygląda tak:

? Would you like to use the recommended Next.js defaults? › - Use arrow-keys. Return to submit.
❯   Yes, use recommended defaults
    TypeScript, ESLint, No React Compiler, Tailwind CSS, No src/ directory, App Router, Cache Components, AGENTS.md, Agent feedback
    No, customize settings

Ustawienia zalecane są prawie dobre, ale włączają dwie rzeczy, których w tym kursie nie chcemy: Cache Components i Agent feedback. Zamiast przeklikiwać kreator, podasz Claude wszystkie odpowiedzi z góry, a on zamieni je na flagi. Z flagami kreator nie zadaje ani jednego pytania, a Ty z góry wiesz, co powstanie.

Czym jest Next.js

Next.js to framework do budowania aplikacji webowych w React. Daje gotowe to, co w samym React składa się ręcznie: strony jako pliki, renderowanie na serwerze i serwer deweloperski. Dokumentacja Reacta (react.dev) wymienia go jako pierwszy z frameworków polecanych do nowych aplikacji.

Next.js ma dwa sposoby układania stron. App Router trzyma strony w folderze app/ i jest zalecany w nowych projektach. Pages Router trzyma je w folderze pages/: to starszy sposób, nadal wspierany. W kursie używamy App Routera.

Polecenie dla Claude Code

Utwórz w Dokumentach nowy, pusty folder projekty, osobno od piracki_statek, bo kreator zakłada w nowym projekcie własne repozytorium Git. Otwórz go w Cursorze (File, Open Folder), uruchom w terminalu claude i przełącz sesję na Manual.

Polecenie dla Claude Code:

Załóż w tym folderze nowy projekt Next.js o nazwie krakens-call przez
npx create-next-app@latest, tak żeby kreator nie zadał żadnego pytania:
TypeScript, ESLint, Tailwind CSS, App Router, bez folderu src/, z plikiem
AGENTS.md, bez Cache Components, bez agent feedback, npm jako menedżer
pakietów. Zanim uruchomisz komendę, pokaż ją i wyjaśnij każdą flagę.
Na koniec uruchom npm run build w nowym projekcie i pokaż wynik.

W poleceniu jest cel, komplet wymagań, prośba o wyjaśnienie przed uruchomieniem i sprawdzian na końcu. Ostatnie zdanie jest najważniejsze: "gotowe" od agenta to meldunek, a wynik builda to dowód.

Co zaproponował Claude: komenda z flagami

Claude wyjaśni flagi i poprosi o zgodę na komendę podobną do tej:

npx create-next-app@latest krakens-call --ts --eslint --tailwind --app --no-src-dir --no-cache-components --agents-md --no-agent-feedback --use-npm

Przeczytaj ją flaga po fladze, zanim klikniesz Yes:

  • krakens-call to nazwa projektu i folderu, który powstanie;
  • --ts włącza TypeScript, --eslint linter ESLint, a --tailwind Tailwind CSS;
  • --app wybiera App Router, a --no-src-dir trzyma kod w app/, bez dodatkowego folderu src/;
  • --no-cache-components wyłącza Cache Components;
  • --agents-md dodaje plik AGENTS.md z instrukcjami dla agentów;
  • --no-agent-feedback wyłącza przygotowywanie przez agentów anonimowych opinii o Next.js;
  • --use-npm instaluje paczki przez npm.

Przedrostek --no- odwraca opcję domyślną, a dokumentacja kreatora pokazuje to na przykładzie --no-ts. Flagi bundlera nie ma, bo Turbopack, bundler Next.js, jest domyślny. Agent feedback przy flagach i tak jest wyłączony, ale piszemy to wprost, żeby komenda mówiła wszystko sama.

Dlaczego bez Cache Components

Cache Components to nowy model pamięci podręcznej w Next.js: strona jest domyślnie przygotowywana z góry, a wszystko, co zależy od konkretnego żądania, trzeba owinąć w <Suspense> albo oznaczyć do zapamiętania. Od wersji 16.4 kreator włącza ten model w ustawieniach zalecanych (stan na listopad 2026).

Przykłady w kolejnych lokacjach są napisane w modelu bez Cache Components. Strona pojedynczego posta w klonie Twittera czyta na przykład numer z adresu na samej górze komponentu, tak jak ta prosta strona statku. params to parametry z adresu, a PageProps to typ, który Next.js przygotowuje dla każdej strony:

export default async function ShipPage({ params }: PageProps<"/statki/[id]">) {
  const { id } = await params;
  return <h1>Statek {id}</h1>;
}

W projekcie z Cache Components npm run build przerywa się na tej stronie komunikatem "Next.js encountered uncached or runtime data during prerendering". Bez Cache Components ta sama strona buduje się bez błędu jako strona dynamiczna. Zespół Next.js zapowiada, że w wersji 17 ten model stanie się domyślny, więc wrócimy do niego w swoim czasie. Dziś wyłączamy go świadomie i wiemy dlaczego.

Co wypisał kreator

Po Twojej zgodzie kreator pracuje około minuty. Na początku wypisze opcje, których nie podałeś, i wartości, jakie dla nich przyjął:

Using defaults for unprovided options:

  --no-react-compiler     No React Compiler (use --react-compiler for React Compiler)
  --import-alias          "@/*"

React Compiler zostaje wyłączony, a alias importów @/* pozwoli pisać w importach @/app/... zamiast ścieżek z kropkami. Potem kreator instaluje paczki, tworzy repozytorium Git i robi pierwszy commit "Initial commit from Create Next App". Koniec poznasz po linii Success! Created krakens-call. Ostrzeżenia npm o przestarzałej paczce i podatnościach to informacja, nie błąd. Nie zgadzaj się na npm audit fix --force: sam npm pisze, że ta komenda wprowadza zmiany łamiące zgodność.

Gdzie teraz pracuje Claude

Projekt powstał w podfolderze krakens-call, a sesja Claude wciąż pracuje folder wyżej, w projekty. Kolejne polecenia mają trafiać do projektu, więc przenieś port: zamknij sesję komendą /exit, otwórz w Cursorze folder krakens-call (File, Open Folder) i w nowym terminalu uruchom claude. Jeśli wolisz zostać w tym samym terminalu, po /exit wpisz:

cd krakens-call && claude

cd przenosi terminal do folderu projektu, a && z lekcji 0_3 uruchamia claude tylko wtedy, gdy przejście się udało. Sprawdź katalog roboczy nad polem polecenia: ścieżka musi kończyć się na krakens-call.

Co powstało: czytamy w Cursorze

Drzewo plików po lewej pokaże taki projekt. Pomijam folder node_modules/, folder .next/, który pojawia się po pierwszym buildzie, i obrazki w public/:

krakens-call/
├── app/
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── public/
├── .gitignore
├── AGENTS.md
├── README.md
├── eslint.config.mjs
├── next-env.d.ts
├── next.config.ts
├── package-lock.json
├── package.json
└── tsconfig.json

Folder app/ to App Router: każdy plik page.tsx w nim to osobna strona. public/ trzyma pliki dostępne wprost pod adresem strony, na przykład obrazki. Zauważ też, czego tu nie ma: pliku CLAUDE.md, pliku tailwind.config ani postcss.config.mjs. Tailwind 4 ustawia się w CSS, o czym w następnej lekcji.

Otwórz app/page.tsx. To strona główna, czyli adres /. Komponent Home zwraca to, co widać w przeglądarce, a w skrócie wygląda tak:

export default function Home() {
  return (
    <div className="flex flex-col flex-1 items-center justify-center bg-zinc-50 font-sans dark:bg-black">
      <main className="flex flex-1 w-full max-w-3xl flex-col items-center justify-between py-32 px-16 bg-white dark:bg-black sm:items-start">
        {/* logo Next.js, nagłówek i linki */}
      </main>
    </div>
  );
}

export default function mówi Next.js, że ta funkcja jest stroną. Długie ciągi w className to klasy Tailwinda, właśnie takie, jakie Claude będzie pisał za Ciebie; czytać je nauczysz się w następnej lekcji. W pełnym pliku jest też nagłówek "To get started, edit the page.tsx file.".

app/layout.tsx to wspólna rama wszystkich stron, kadłub, w którym płyną kolejne pokłady. Zobaczysz w nim obiekt metadata opisany typem Metadata i funkcję RootLayout, która dostaje children opisane typem LayoutProps:

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html
      lang="en"
      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
    >
      <body className="min-h-full flex flex-col">{children}</body>
    </html>
  );
}

metadata to tytuł i opis strony, widoczne między innymi na karcie przeglądarki. children to treść aktualnej strony, którą layout wkłada do <body>, a geistSans i geistMono to fonty Geist wczytane na górze pliku.

Teraz plik, który potwierdza, że flagi zadziałały. Otwórz next.config.ts, czyli konfigurację Next.js:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  turbopack: {
    rules: {
      "*.css": {
        loaders: ["@tailwindcss/turbopack"],
        as: "*.css",
      },
    },
  },
};

export default nextConfig;

Jedyna ustawiona opcja to reguła Turbopacka, która przepuszcza pliki CSS przez Tailwinda. Nie ma tu linii cacheComponents: true ani partialPrefetching: true, które dopisują ustawienia zalecane, ani bloku experimental z agentFeedback. Brak tych linii to dowód, że obie flagi --no- zadziałały.

Na koniec AGENTS.md, plik z instrukcjami dla agentów, takich jak Claude Code. Kreator wpisał do niego jeden blok z nagłówkiem "This is NOT the Next.js you know". Blok ostrzega agenta, że ta wersja Next.js różni się od tego, czego model mógł się nauczyć, i każe mu przed pisaniem kodu czytać dokumentację z folderu node_modules/next/dist/docs/. Claude Code czyta AGENTS.md, gdy w projekcie nie ma pliku CLAUDE.md, więc ta wskazówka trafia do każdej sesji w tym folderze. Blok odtwarza też samo next dev, więc go nie usuwaj. Własne zasady projektu dopiszesz później w tej lokacji.

Dowód zamiast słowa: npm run build

Ostatnie zdanie polecenia kazało Claude zbudować projekt. W wyniku szukasz takich linii:

▲ Next.js 16.4.6 (Turbopack)
✓ Compiled successfully in 1562ms
  Running TypeScript ...
  Finished TypeScript in 803ms ...
✓ Generating static pages using 5 workers (4/4) in 220ms

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

○  (Static)  prerendered as static content

"Compiled successfully" znaczy, że kod się skompilował, a linie o TypeScripcie, że typy się zgadzają. Tabela Route wymienia strony: / to strona główna, /_not-found to strona błędu 404 dodana przez Next.js, a kółko oznacza stronę przygotowaną z góry. Build nie uruchamia jednak lintera, więc błędy wykrywane przez ESLint przejdą przez niego niezauważone. Lint to osobna komenda, npm run lint, która przy czystym kodzie nie wypisuje nic poza swoją nazwą. Od dziś prosisz o oba sprawdziany po każdej większej zmianie.

Strona w przeglądarce i Fast Refresh

Serwer deweloperski uruchamiasz sam, w drugim terminalu Cursora (Control+Shift+` na Macu, Ctrl+Shift+` na Windowsie i Linuksie). Rada kapitana: tak jest wygodniej, bo serwer działa, dopóki go nie zatrzymasz, a jego komunikaty chcesz mieć przed oczami. W folderze krakens-call wpisz npm run dev i poczekaj na taki wynik:

▲ Next.js 16.4.6 (Turbopack)
- Local:         http://localhost:3000
- Network:       http://192.168.1.10:3000
✓ Ready in 170ms

Adres z linii Local otwórz w przeglądarce: zobaczysz stronę startową Next.js. Adres Network działa tylko w Twojej sieci domowej.

Teraz pierwsza zmiana w projekcie, w sesji Claude:

Polecenie dla Claude Code:

W @app/page.tsx zamień tekst nagłówka h1 na "Ahoj, Piraci!" i nic
więcej nie zmieniaj.

Gdy Claude zapisze plik, spójrz na przeglądarkę: nagłówek zmieni się sam, bez odświeżania. W Next.js ta funkcja nazywa się Fast Refresh, potocznie hot reload. W Cursorze otwórz Source Control: na liście zmian jest tylko app/page.tsx, a diff pokazuje stary i nowy nagłówek. Jeśli zmienił się inny plik, Claude zrobił więcej, niż prosiłeś.

Kreator zrobił już pierwszy commit, więc to będzie drugi wpis w dzienniku. Napisz Claude "Zrób commit z opisem tej zmiany" i przeczytaj komendy, zanim się zgodzisz, tak jak w lekcji 0_6.

Przegląd kapitana

Zanim uznasz okręt za zwodowany, sprawdź cztery rzeczy:

  1. next.config.ts nie ma cacheComponents: true. Jeśli ma, kreator dostał inne flagi, niż prosiłeś.
  2. Katalog roboczy sesji kończy się na krakens-call, a nie na projekty.
  3. Wynik builda widziałeś na własne oczy, a nie tylko w podsumowaniu Claude.
  4. package.json zawiera tylko paczki z kreatora: nic nie zostało doinstalowane bez Twojej prośby.

Typowe błędy agenta przy tym zadaniu: uruchamia kreator z --yes, który bierze zapisane wcześniej ustawienia albo zalecane, a w zalecanych Cache Components są włączone, albo zakłada projekt w złym folderze, na przykład wewnątrz piracki_statek. Oba wyłapiesz w prośbie o zgodę, jeśli przeczytasz komendę i katalog, zanim klikniesz Yes.

Następny krok

Projekt stoi, strona działa, a dziennik ma dwa wpisy. W następnej lekcji Claude zbuduje pierwszą sekcję strony Kraken's Call w Tailwind CSS, a Ty nauczysz się czytać jego klasy. W edytorze poniżej obejrzysz prostą stronę i layout w stylu App Routera.

Pamiętaj: dobry rozkaz na start rejsu oszczędza tygodnie łatania kadłuba.

Kod do tej lekcji: page.tsx
// Next.js 16 App Router - Podstawowa struktura strony

export default function Home() {
  return (
    <main className="min-h-screen p-24">
      <div className="max-w-5xl mx-auto">
        <h1 className="text-4xl font-bold mb-8">
          Witaj w Next.js 16!
        </h1>

        <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
          <div className="border border-gray-300 p-6 rounded-lg">
            <h2 className="text-2xl font-semibold mb-4">
              App Router
            </h2>
            <p className="text-gray-600">
              To jest strona w folderze app/. Każdy plik page.tsx to osobna strona.
            </p>
          </div>

          <div className="border border-gray-300 p-6 rounded-lg">
            <h2 className="text-2xl font-semibold mb-4">
              Server Components
            </h2>
            <p className="text-gray-600">
              Domyślnie wszystkie komponenty w App Router są Server Components.
            </p>
          </div>

          <div className="border border-gray-300 p-6 rounded-lg">
            <h2 className="text-2xl font-semibold mb-4">
              TypeScript
            </h2>
            <p className="text-gray-600">
              Next.js ma wbudowane wsparcie dla TypeScript out-of-the-box.
            </p>
          </div>

          <div className="border border-gray-300 p-6 rounded-lg">
            <h2 className="text-2xl font-semibold mb-4">
              Tailwind CSS
            </h2>
            <p className="text-gray-600">
              Stylowanie przez utility classes bezpośrednio w JSX.
            </p>
          </div>
        </div>
      </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. W jakim folderze znajdują się strony w Next.js App Router?

  2. 2. Która komenda uruchamia development server w Next.js?

  3. 3. Czym jest Next.js?

  4. 4. Czym jest plik app/page.tsx w Next.js App Router?

  5. 5. Za co odpowiada plik app/layout.tsx?

  6. 6. Co oznacza Fast Refresh (potocznie hot reload) w Next.js?

  7. 7. Który router Next.js jest zalecany w nowych projektach?

Zadania praktyczne w grze

  • Edytor kodu

    Zapytaj AI w Cursorze, jak stworzyć projekt Next.js, i wpisz w pliku commands.sh komendę npx, którą dostaniesz.

  • Układanie w pionie

    Ułóż kroki, po których zobaczysz zmianę od Claude w przeglądarce bez odświeżania:

  • Klikanie w kolejności

    Zbuduj komendę uruchamiającą development server:

  • Układanie w pionie

    Ułóż kroki zakładania projektu z Claude Code, od polecenia do dowodu:

  • Układanie w poziomie

    Ułóż komendę, która przenosi terminal do nowego projektu i uruchamia w nim Claude Code (od lewej do prawej):

  • Klikanie w kolejności

    Zbuduj komendę, którą Claude sprawdza, czy projekt się buduje:

  • Układanie w poziomie

    Ułóż części adresu lokalnej aplikacji Next.js (od lewej do prawej):

  1. PytanieQuiz: Next.js App Router
  2. PytanieQuiz: Development server
  3. Zadanie z kodemPraktyka: Stwórz projekt Next.js
  4. Ułóż w kolejnościSortowanie: Fast Refresh w praktyce
  5. Kliknij w kolejnościSortowanie: Komenda uruchomienia serwera
  6. PytanieQuiz: Czym jest Next.js?
  7. Ułóż w kolejnościSortowanie: Od polecenia do dowodu
  8. PytanieQuiz: Plik page.tsx
  9. Ułóż w kolejnościSortowanie: Sesja w folderze projektu
  10. PytanieQuiz: Layout aplikacji
  11. Kliknij w kolejnościSortowanie: Komenda sprawdzianu builda
  12. PytanieQuiz: Fast Refresh
  13. Ułóż w kolejnościSortowanie: Adres lokalnej aplikacji
  14. PytanieQuiz: App Router vs Pages Router

Przydatne artykuły