Astro i Headless CMS: Integracja Sanity, Storyblok, Strapi

W serii o Astro trzymaliśmy treść w plikach i jest to świetne rozwiązanie dla technicznego bloga pisanego przez programistów (takich, jak właśnie blog StriveLab). W projekcie z redakcją wygląda to inaczej, ponieważ klient nie powinien edytować MDX-a w repozytorium, żeby zmienić opis usługi. Do tego właśnie służy headless CMS, a Astro spina się z nim bez problemowo.

Czym jest headless CMS i czym różni się od WordPressa

Klasyczny WordPress robi dwie rzeczy jednocześnie. Z jednej strony daje panel do pisania treści, a z drugiej generuje stronę, która ją wyświetla. Headless CMS rozdziela te role:

• Głowa (frontend) jest odcięta od reszty, a treść nie jest renderowana przez CMS.
• Backend treści, czyli panel do pisania, baza i API, z którego pobierasz dane.

Frontend budujesz osobno, w tym przypadku w Astro. Dzięki temu zyskujesz pełną kontrolę nad HTML-em, wydajnością i sposobem renderowania, podczas gdy redaktor swobodnie pracuje w panelu. To esencja headlessa, który oznacza wygodę dla redakcji bez oddawania frontendu CMS-owi.

Dwa sposoby podłączenia CMS do Astro

Astro daje dwie ścieżki integracji, a wybór zależy od tego, czy pracujesz na kolekcji treści, czy na pojedynczym zapytaniu z większą liczbą warunków.

Wariant 1: loader w Content Collections (dla blogów i list)

Najczystsze podejście dla treści, która jest kolekcją (artykuły, produkty, autorzy). Definiujesz loader w content.config.ts, a CMS staje się źródłem typowanej kolekcji — czytanej tak samo jak pliki lokalne:

// src/content.config.ts — przykład ze Storyblokiem
import { defineCollection } from 'astro:content'
import { storyblokLoader } from '@storyblok/astro'
import { z } from 'astro/zod'
 
const articles = defineCollection({
  loader: storyblokLoader({
    accessToken: import.meta.env.STORYBLOK_TOKEN,
    contentTypes: ['article'],
    version: 'published',
  }),
  schema: z.object({
    title: z.string(),
    body: z.string(),
    seo: z.object({
      title: z.string(),
      description: z.string(),
    }),
  }),
})
 
export const collections = { articles }

Efekt: treść z CMS i treść z plików obsługujesz identycznie przez getCollection('articles'), z tym samym typowaniem i walidacją Zod. CMS staje się jednym z wielu źródeł, bez specjalnej ścieżki w kodzie.

---
import { getCollection } from 'astro:content'
 
const articles = await getCollection('articles')
---
 
<ul>
  {articles.map((article) => (
    <li><a href={`/blog/${article.id}/`}>{article.data.title}</a></li>
  ))}
</ul>

Wariant 2: bezpośrednie API (dla dynamicznych zapytań i podglądu)

Zamiast loadera wywołujesz API CMS bezpośrednio we frontmatterze .astro, co daje pełną kontrolę nad zapytaniem — projekcje, filtry, relacje. Sanity używa do tego @sanity/client z językiem zapytań GROQ:

---
// src/pages/produkt/[slug].astro — przykład z Sanity
import { createClient } from '@sanity/client'
 
const client = createClient({
  projectId: import.meta.env.SANITY_PROJECT_ID,
  dataset: 'production',
  useCdn: true,
  apiVersion: '2024-01-01',
})
 
const { slug } = Astro.params
 
const product = await client.fetch(
  `*[_type == "product" && slug.current == $slug][0]`,
  { slug },
)
---
 
<h1>{product.name}</h1>
<p>{product.price} zł</p>

Pełna kontrola nad zapytaniem (projekcje, filtry, relacje) jest możliwa, ale kosztem spójności z systemem kolekcji. Jest to naturalny wybór dla pojedynczych, dynamicznych stron oraz trybu podglądu.

SEO: treść z CMS musi trafić do HTML

Najczęstszy błąd przy integracji CMS z frontendem to pobieranie treści po stronie klienta. Dlaczego? Ponieważ, wtedy crawler dostaje pusty szkielet, a treść dochodzi dopiero po wykonaniu JavaScriptu, co jest bardzo szkodliwe dla SEO. W Astro tego problemu nie ma, bo treść pobierasz w build time albo na serwerze:

• SSG w Astro pobiera treść z CMS podczas builda i wstawia ją do statycznego HTML. Idealne dla bloga i stron, które zmieniają się rzadko.
• SSR w Astro pobiera treść na żądanie i renderuje na serwerze, jest to potrzebne przy podglądzie na żywo i częstych zmianach.

W obu wypadkach Google dostaje gotową treść w pierwszej odpowiedzi, bez kosztu renderowania po stronie klienta i bez ryzyka, że ważna treść nie zostanie zaindeksowana. Szerzej o tym w artykule SEO w Astro.

Podgląd na żywo — komfort redakcji

Najmocniejszy argument za CMS dla redakcji to podgląd na żywo (live preview) — redaktor widzi zmiany na prawdziwym layoucie, jeszcze zanim opublikuje. To wymaga trybu serwerowego, ponieważ treść musi odświeżać się na żądanie:

• Tryb draft/preview w Astro pobiera nieopublikowaną wersję treści (version: 'draft' w loaderze albo dedykowany klient podglądu).
• CMS-y takie jak Storyblok i Sanity dostarczają dedykowane narzędzia podglądu (Visual Editing) wpinane w ten tryb.

Który CMS wybrać

Astro wspiera 50+ systemów. Cztery najlepiej zintegrowane:

Wybór CMS-a to decyzja o redakcji i danych, nie o Astro — Astro pobierze treść z każdego z nich tym samym wzorcem (loader albo bezpośrednie API).

Kiedy NIE używać CMS — zostań przy plikach

Headless CMS dokłada zależność, koszt i punkt awarii. Nie zawsze się opłaca:

• Treść piszą programiści — pliki Markdown/MDX w repozytorium dają wersjonowanie w Git, brak zewnętrznej zależności i pełną kontrolę. CMS byłby tu zbędnym narzutem.

• Mały, statyczny serwis — strona firmowa na kilka podstron rzadko potrzebuje panelu. Content Collections w zupełności wystarczą.

• Budżet i czas są napięte, czyli integracja CMS, modelowanie treści i konfiguracja podglądu to realna praca. Dla MVP pliki są szybsze.

CMS powinien być wtedy stosowany, kiedy komfort redakcji nietechnicznej albo wielokanałowość treści przeważają nad prostotą plików. Dla mnie osobiście, praca na plikach mdx jest dużo bardziej wygodna i efektywna, ale to moja własna obserwacja, być może wykrzywiona kontrolą nad innymi elementami poza tekstem (komponenty, prosty kod etc.).