Kurs vibe coding z Claude Code · Moduł 12: Klon Medium

Mapa dla wyszukiwarek: metadane i mapa strony

8 min czytania
W tej lekcji9

Kronika ma już teksty ale wyślij komuś link do artykułu i zobacz kartę przeglądarki: "Create Next App". Ten tytuł i opis "Generated by create next app" zostały w app/layout.tsx z kreatora z lekcji 11_1 i stoją na każdej stronie. Komunikator, który pokazuje podgląd linku, i wyszukiwarka, która decyduje, co wpisać w wynikach, widzą to samo. Do tego nikt im nie mówi, jakie teksty w ogóle istnieją. Artykuł bez metadanych i bez mapy strony jest jak skrzynia zakopana bez mapy: skarb jest, ale nikt nie wie gdzie.

Czego się nauczysz

  • kazać Claude przeczytać aktualną dokumentację metadanych Next.js, zanim powstanie kod;
  • przeczytać generateMetadata, który bierze tytuł i opis z artykułu;
  • zbudować sitemap.xml tylko z opublikowanych tekstów, z prawdziwą datą zmiany;
  • sprawdzić wynik komendą curl na zbudowanej aplikacji.

Najpierw dokumentacja

Metadane to tytuł, opis i inne znaczniki w <head> strony, których czytelnik nie widzi w treści, a czytają je przeglądarki, komunikatory i wyszukiwarki. API metadanych w Next.js zmieniało się między wersjami, więc zaczynasz od zwiadu, jak w lekcjach 5_4 i 9_4. Tym razem nie potrzeba sieci: z lekcji 1_2 wiesz, że Next.js 16 dołącza dokumentację swojej wersji w node_modules/next/dist/docs/, a AGENTS.md każe Claude ją czytać.

Polecenie dla Claude Code:

Nie pisz kodu. Przeczytaj w node_modules/next/dist/docs/ strony
o generateMetadata, sitemap, robots i JSON-LD. Napisz: czym różni się
generateMetadata od stałego metadata, czy sitemap.ts liczy się przy
buildzie czy przy każdym zapytaniu i jak bezpiecznie wstawić JSON-LD.
Przy każdym ustaleniu ścieżka pliku. Potem plan dla /artykuly/[id].

Raport porównaj z plikami, które otwierasz sam w Cursorze. U nas dokumentacja mówi trzy rzeczy, które zmieniają kod. Stały obiekt metadata jest jeden dla całego segmentu trasy, a generateMetadata dostaje params i może przeczytać dane, przy czym obu naraz z jednego segmentu eksportować nie wolno. sitemap.ts to specjalna trasa, którą Next.js domyślnie zapamiętuje przy buildzie, chyba że użyje API zależnego od zapytania. A JSON.stringify nie oczyszcza tekstu z niebezpiecznych znaków.

Polecenie dla Claude Code

Plan wygląda dobrze, więc zamawiasz zmiany. Opis artykułu bierzesz z funkcji excerpt, którą naprawiłeś w lekcji 11_4, a datę zmiany z nowego pola danych.

Dodaj metadane do Captain's Chronicle według planu.
1. app/layout.tsx: zamiast "Create Next App" tytuł z szablonem
   "%s | Captain's Chronicle", opis kroniki, lang="pl", metadataBase
   z SITE_URL (lib/site.ts, lokalnie http://localhost:3000).
2. /artykuly/[id]: generateMetadata z tytułem artykułu, opisem
   z @lib/excerpt.ts i Open Graph typu article z datami. Tekst
   nieopublikowany dostaje noindex. JSON-LD typu Article.
3. app/sitemap.ts: tylko opublikowane artykuły, lastModified z danych:
   nowe pole updatedAt w Article (a3 zmienił się 15 listopada),
   a gdy go nie ma, publishedAt.
4. app/robots.ts: bez /api/ i /pisz, z adresem mapy.
Gotowe, gdy lint, tsc, testy i build przejdą, a curl na npm start
pokaże tytuł, opis, mapę i robots.txt.

Co napisał Claude: metadane z artykułu

Otwórz app/layout.tsx. Szablon tytułu dokleja nazwę kroniki do tytułu każdej podstrony:

// app/layout.tsx
export const metadata: Metadata = {
  metadataBase: new URL(SITE_URL),
  title: { default: "Captain's Chronicle", template: "%s | Captain's Chronicle" },
  description: "Opowieści z rejsów spisane przez załogę.",
};

Według dokumentacji template działa tylko w segmentach poniżej layoutu i wymaga default, który dostają strony bez własnego tytułu. metadataBase pozwala pisać niżej ścieżki zamiast pełnych adresów. Teraz app/artykuly/[id]/page.tsx:

// app/artykuly/[id]/page.tsx
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { id } = await params;
  const article = getArticle(id);
  if (!article) return {};
  const description = excerpt(article);
  return {
    title: article.title,
    description,
    alternates: { canonical: `/artykuly/${article.id}` },
    openGraph: {
      type: "article",
      title: article.title,
      description,
      url: `/artykuly/${article.id}`,
      publishedTime: article.publishedAt,
      modifiedTime: article.updatedAt ?? article.publishedAt,
    },
    robots: isPublished(article) ? undefined : { index: false },
  };
}

Props to ten sam typ z params jako obietnicą, którego używa strona. Każdy artykuł dostaje własny tytuł i opis. Open Graph to znaczniki og:, z których komunikatory budują podgląd linku. canonical wskazuje główny adres strony. Tekst zgłoszony, ale nieopublikowany, dostaje noindex: redaktor może go obejrzeć, a wyszukiwarka dostaje prośbę, żeby go nie indeksowała.

Co napisał Claude: mapa strony

Mapa strony (sitemap) to plik XML z listą adresów. Dokumentacja Next.js pisze, że pomaga robotom wyszukiwarek sprawniej indeksować stronę. Przy każdym adresie może stać data ostatniej zmiany, a protokół map stron (sitemaps.org) zastrzega, że ma to być data zmiany samej strony, a nie chwila, w której powstała mapa. Dlatego Claude zaczął od danych w lib/articles.ts:

// lib/articles.ts
  publishedAt: string; // ISO
  updatedAt?: string; // ISO, ostatnia zmiana po publikacji

Znak zapytania robi z updatedAt pole opcjonalne: tekst, którego nikt nie poprawiał po publikacji, go nie ma i wtedy liczy się publishedAt. Tekst Mary z lekcji 11_4 dostał updatedAt, bo zmienił się po publikacji. Teraz otwórz app/sitemap.ts:

// app/sitemap.ts
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  await connection(); // publikacje zmieniają się po buildzie
  return ARTICLES.filter(isPublished).map((article) => ({
    url: `${SITE_URL}/artykuly/${article.id}`,
    lastModified: article.updatedAt ?? article.publishedAt,
  }));
}

filter(isPublished) wyrzuca szkice: do mapy trafia tylko to, co czytelnik naprawdę może przeczytać. lastModified pochodzi z danych, więc mapa mówi prawdę o dacie zmiany każdego tekstu. connection() z next/server każe liczyć mapę przy każdym zapytaniu. Bez tej linii build oznaczył u nas /sitemap.xml jako statyczny (○). Po publikacji tekstu a4 przez curl z lekcji 11_3 mapa dalej miała trzy adresy. Z connection() trasa dostała ƒ, a a4 pojawił się od razu.

app/robots.ts mówi robotom, czego nie odwiedzać, i podaje adres mapy:

// app/robots.ts
export default function robots(): MetadataRoute.Robots {
  return {
    rules: { userAgent: "*", allow: "/", disallow: ["/api/", "/pisz"] },
    sitemap: `${SITE_URL}/sitemap.xml`,
  };
}

Ta trasa została statyczna, więc SITE_URL czyta przy buildzie. U nas zmienna ustawiona dopiero przy npm start zmieniła adresy w mapie, a robots.txt dalej pokazywał http://localhost:3000/sitemap.xml. Na produkcji ustawiasz SITE_URL, zanim ruszy build.

Co napisał Claude: JSON-LD

JSON-LD to dane strukturalne: opis strony w formacie, który wyszukiwarki czytają jak formularz (typ, tytuł, daty). Dokumentacja Next.js zaleca zwykły znacznik <script> w stronie:

// app/artykuly/[id]/page.tsx
<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, "\\u003c") }}
/>

jsonLd to obiekt z @type: "Article", tytułem, opisem i obiema datami. Tytuł pisze autor, a tytuł z </script> w środku zamknąłby znacznik i resztę potraktował jak HTML. Dlatego replace zamienia każde < na \u003c, jak radzi dokumentacja.

Sprawdzian: curl na zbudowanej aplikacji

Metadane ocenia się w HTML, który dostaje robot, a nie w kodzie. Uruchom npm run build && npm start i w drugiej karcie terminala:

curl -s localhost:3000/artykuly/a3 | grep -oE '<title>[^<]*</title>|<meta name="description"[^>]*>|<meta property="og:(title|type)"[^>]*>'
curl -s localhost:3000/artykuly/a4 | grep -o '<meta name="robots"[^>]*>'
curl -s localhost:3000/sitemap.xml
curl -s localhost:3000/robots.txt

grep -o wypisuje tylko pasujące kawałki, a -E pozwala zapisać kilka wzorców rozdzielonych |. U nas pierwsza komenda wypisała:

<title>Kucharz okrętowy radzi: suchary na sześć tygodni | Captain&#x27;s Chronicle</title>
<meta name="description" content="Suchar musi być twardy jak pokład, inaczej nie przetrwa rejsu."/>
<meta property="og:title" content="Kucharz okrętowy radzi: suchary na sześć tygodni"/>
<meta property="og:type" content="article"/>

&#x27; to apostrof zapisany w HTML. Druga komenda dała <meta name="robots" content="noindex"/> dla zgłoszonego a4. Mapa miała trzy adresy, a1, a2 i a3, z datami z danych, przy a3 2026-11-15T07:30:00Z z pola updatedAt. W robots.txt stały Disallow: /api/, Disallow: /pisz i adres mapy. Sprawdź też adres, którego nie ma: /artykuly/zzz odpowiedział u nas kodem 404, z noindex, który Next.js dokleja sam, i z domyślnym tytułem z layoutu. Tu generateMetadata zwraca pusty obiekt, a stronę zatrzymuje notFound().

Przegląd kapitana

  1. Tytuł każdego artykułu inny. Typowy błąd agenta to stały export const metadata w stronie artykułu: ten sam tytuł dla każdego tekstu. Drugi to przepisany przykład z dokumentacji z acme.com albo zostawione "Create Next App". Wyszukaj w projekcie oba napisy.
  2. Szkice poza mapą. W sitemap.xml nie ma a4, dopóki redaktor go nie opublikuje, a jego strona ma noindex.
  3. Data z danych. Przykład w dokumentacji ma lastModified: new Date() i Claude chętnie go kopiuje. U nas dwa zapytania w odstępie dwóch sekund dały dwie różne daty: mapa twierdziła, że każdy tekst zmienia się co chwilę.
  4. Prawdziwy adres. Na produkcji w mapie i w robots.txt nie ma localhost.
  5. Bezpieczny JSON-LD. Przy JSON.stringify w <script> stoi replace znaku <.

Metadane i mapa nie obiecują miejsca w wynikach wyszukiwania. Mówią robotom, co jest na stronie i gdzie szukać reszty, a o kolejności wyników decyduje wyszukiwarka.

Następny krok

Poproś o commit "Metadane, mapa strony i robots.txt". Cztery komendy curl powtórzysz przy każdej nowej trasie, więc zamień je w skill z lekcji 6_1: "Zapisz sprawdzian SEO z tej rozmowy jako skill /seo-check w .claude/skills/: build, start, curl tytułu, opisu, og:, mapy i robots.txt, wynik w tabeli. Tylko ja go uruchamiam." W edytorze poniżej czeka podgląd kroniki: wybierz artykuł, zobacz jego znaczniki i mapę, a potem włącz błąd agenta "jeden tytuł dla wszystkich" i błąd z new Date().

Zapamiętaj: mapa bez skarbu to tylko kartka, ale skarb bez mapy zostaje pod piaskiem.

Kod do tej lekcji: App.jsx
// Podgląd metadanych i mapy strony z przykładowych artykułów kroniki
import { useState } from 'react';

const SITE_URL = 'https://kronika.example';
const SITE_NAME = "Captain's Chronicle";

const ARTICLES = [
  { id: 'a1', title: 'Jak przetrwać sztorm na Atlantyku', text: 'Sztorm przyszedł nocą, a załoga spała po długiej wachcie.', status: 'published', publishedAt: '2026-11-10T08:00:00Z' },
  { id: 'a2', title: 'Mapa skarbów, której nie było', text: 'Mapa miała trzy krzyżyki i żadnego skarbu.', status: 'published', publishedAt: '2026-11-12T08:00:00Z' },
  { id: 'a3', title: 'Kucharz okrętowy radzi: suchary na sześć tygodni', text: 'Suchar musi być twardy jak pokład, inaczej nie przetrwa rejsu.', status: 'published', publishedAt: '2026-11-14T08:00:00Z', updatedAt: '2026-11-15T07:30:00Z' },
  { id: 'a4', title: 'Wachta nocna bez kawy', text: 'O trzeciej nad ranem gwiazdy są jedynym zegarem.', status: 'submitted', publishedAt: '2026-11-15T08:00:00Z' },
];

function excerpt(article, max = 160) {
  const text = article.text.trim();
  return text.length > max ? text.slice(0, max - 1).trimEnd() + '…' : text;
}

// Jak generateMetadata: tytuł i opis z artykułu. Wersja agenta: jeden stały obiekt metadata.
function metadataFor(article, published, staticTitle) {
  if (staticTitle) {
    return { title: 'Artykuł | ' + SITE_NAME, description: 'Opowieści z rejsów spisane przez załogę.', ogType: 'website', robots: null };
  }
  return {
    title: article.title + ' | ' + SITE_NAME,
    description: excerpt(article),
    ogType: 'article',
    robots: published ? null : 'noindex',
  };
}

function sitemapXml(articles, isPublished, options) {
  const rows = articles
    .filter((a) => options.drafts || isPublished(a))
    .map((a) => {
      const lastmod = options.newDate ? options.generatedAt : a.updatedAt ?? a.publishedAt;
      return '  <url>\n    <loc>' + SITE_URL + '/artykuly/' + a.id + '</loc>\n    <lastmod>' + lastmod + '</lastmod>\n  </url>';
    });
  return '<urlset>\n' + rows.join('\n') + '\n</urlset>';
}

export default function App() {
  const [selectedId, setSelectedId] = useState('a3');
  const [publishedA4, setPublishedA4] = useState(false);
  const [staticTitle, setStaticTitle] = useState(false);
  const [newDate, setNewDate] = useState(false);
  const [drafts, setDrafts] = useState(false);
  const [generatedAt, setGeneratedAt] = useState('2026-11-15T09:00:00.000Z');

  const isPublished = (a) => a.status === 'published' || (a.id === 'a4' && publishedA4);
  const article = ARTICLES.find((a) => a.id === selectedId);
  const meta = metadataFor(article, isPublished(article), staticTitle);
  const xml = sitemapXml(ARTICLES, isPublished, { drafts, newDate, generatedAt });

  return (
    <div className="min-h-screen bg-gray-50 p-4 text-gray-900">
      <div className="mx-auto max-w-xl space-y-4 rounded-xl bg-white p-4 shadow-sm">
        <label className="block text-sm">
          Artykuł:{' '}
          <select value={selectedId} onChange={(e) => setSelectedId(e.target.value)} className="rounded border border-gray-300">
            {ARTICLES.map((a) => (
              <option key={a.id} value={a.id}>
                {a.id}: {a.title} {isPublished(a) ? '' : '(zgłoszony)'}
              </option>
            ))}
          </select>
        </label>

        <div className="rounded-lg border border-gray-200 p-3">
          <p className="text-xs uppercase text-gray-500">Podgląd linku w komunikatorze</p>
          <p className="font-semibold text-blue-800">{meta.title}</p>
          <p className="text-sm text-gray-700">{meta.description}</p>
          <p className="text-xs text-gray-500">{SITE_URL}/artykuly/{article.id}</p>
        </div>

        <pre aria-label="Znaczniki w head" className="overflow-x-auto rounded bg-gray-900 p-3 text-xs text-green-200">
          {'<title>' + meta.title + '</title>\n'}
          {'<meta name="description" content="' + meta.description + '"/>\n'}
          {'<meta property="og:type" content="' + meta.ogType + '"/>'}
          {meta.robots ? '\n<meta name="robots" content="' + meta.robots + '"/>' : ''}
        </pre>
      </div>

      <div className="mx-auto mt-3 max-w-xl space-y-2 rounded-xl bg-white p-4 text-sm shadow-sm">
        <p className="font-semibold">sitemap.xml</p>
        <pre aria-label="Mapa strony" className="overflow-x-auto rounded bg-gray-100 p-3 text-xs">{xml}</pre>
        <div className="flex flex-wrap gap-2">
          <button type="button" onClick={() => setGeneratedAt(new Date().toISOString())} className="rounded bg-gray-900 px-3 py-1 text-white">
            Pobierz mapę jeszcze raz
          </button>
          <button type="button" disabled={publishedA4} onClick={() => setPublishedA4(true)} className="rounded bg-gray-700 px-3 py-1 text-white disabled:opacity-50">
            Redaktor publikuje a4
          </button>
        </div>
      </div>

      <div className="mx-auto mt-3 max-w-xl space-y-2 rounded-xl bg-gray-900 p-4 text-sm text-white">
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={staticTitle} onChange={(e) => setStaticTitle(e.target.checked)} />
          Błąd agenta: jeden tytuł dla wszystkich (stałe metadata)
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={newDate} onChange={(e) => setNewDate(e.target.checked)} />
          Błąd agenta: lastModified: new Date()
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={drafts} onChange={(e) => setDrafts(e.target.checked)} />
          Błąd agenta: szkice w mapie
        </label>
      </div>
    </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. Agent "naprawił" błąd zajawki: owinął kod w try/catch, a catch zwraca pusty napis. Co się dzieje?

  2. 2. Dodajesz serwer MCP Sentry z opcją --scope project. Gdzie trafia konfiguracja i kto ją dostaje?

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

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj pracę z Claude Code nad błędem, który zgłosił Sentry:

  • Układanie w poziomie

    Ułóż komendę w zapisie z dokumentacji Claude Code: najpierw opcja transportu, potem nazwa serwera i adres:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować linię mapy strony z datą zmiany wziętą z danych artykułu:

  1. Ułóż w kolejnościBłąd z Sentry krok po kroku
  2. PytaniePusty catch w poprawce
  3. Ułóż w kolejnościDodanie serwera MCP po HTTP
  4. PytanieZakres project
  5. PytanieCLI czy MCP
  6. PytanieDo czego /mcp
  7. Kliknij w kolejnościData zmiany z danych
  8. PytaniegenerateMetadata czy metadata
  9. PytanieZgłoszony tekst a mapa strony
  10. Projekt do wysłaniaWyślij Captain's Chronicle do mentora
  11. WideoPodsumowanie modułu

Przydatne artykuły