Kurs vibe coding z Claude Code · Moduł 12: Klon Medium
Mapa dla wyszukiwarek: metadane i mapa strony
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.xmltylko z opublikowanych tekstów, z prawdziwą datą zmiany; - sprawdzić wynik komendą
curlna 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 publikacjiZnak 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.txtgrep -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'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"/>' 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
- Tytuł każdego artykułu inny. Typowy błąd agenta to stały
export const metadataw stronie artykułu: ten sam tytuł dla każdego tekstu. Drugi to przepisany przykład z dokumentacji zacme.comalbo zostawione "Create Next App". Wyszukaj w projekcie oba napisy. - Szkice poza mapą. W
sitemap.xmlnie maa4, dopóki redaktor go nie opublikuje, a jego strona manoindex. - 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ę. - Prawdziwy adres. Na produkcji w mapie i w
robots.txtnie malocalhost. - Bezpieczny JSON-LD. Przy
JSON.stringifyw<script>stoireplaceznaku<.
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. Agent "naprawił" błąd zajawki: owinął kod w try/catch, a catch zwraca pusty napis. Co się dzieje?
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:
Zadania po tej lekcji
- Ułóż w kolejnościBłąd z Sentry krok po kroku
- PytaniePusty catch w poprawce
- Ułóż w kolejnościDodanie serwera MCP po HTTP
- PytanieZakres project
- PytanieCLI czy MCP
- PytanieDo czego /mcp
- Kliknij w kolejnościData zmiany z danych
- PytaniegenerateMetadata czy metadata
- PytanieZgłoszony tekst a mapa strony
- Projekt do wysłaniaWyślij Captain's Chronicle do mentora
- WideoPodsumowanie modułu