Integracja Astro i Payload CMS: Szybka strona bez limitów

Dlaczego samodzielne hostowanie plus darmowy front to rewelacja kosztowa

Rozdzielasz dwa koszty, które w modelu SaaS są ze sobą sklejone, czyli koszt serwowania strony oraz koszt zarządzania treścią.

Front w Astro to po buildzie zbiór statycznych plików HTML i takie pliki hostujesz za darmo na Vercelu, Netlify czy Cloudflare Pages. Ich darmowe plany spokojnie udźwigną nawet duży ruch, ponieważ serwowanie plików statycznych jest tanie, a sieci CDN doskonale je buforują.

Treść trzyma Payload, który stawiasz na własnym VPS-ie - Payload jest open-source na licencji MIT — nie płacisz za licencję ani za liczbę zapytań do API. Płacisz tylko za serwer, na którym wszystko działa.

W architekturze statycznej Astro odpytuje Payload tylko podczas builda, a nie przy każdej wizycie użytkownika. Nawet jeśli stronę odwiedzi milion osób, Payload nie dostaje miliona zapytań, ponieważ dostaje ich tyle, ile masz buildów. Twój VPS z Payload może być więc skromny i tani, ponieważ nie obsługuje ruchu użytkowników, ale sam proces budowania strony.

Przy milionach odsłon różnica w kosztach robi się dramatyczna i właśnie dlatego ten zestaw tak dobrze się skaluje finansowo.

Do tego dochodzi argument prawny, czyli dane fizycznie leżą tam, gdzie postawisz serwer. To podstawowy wymóg dla projektów, które muszą trzymać dane w określonej jurysdykcji albo pod pełną kontrolą (sektor publiczny, finanse, ochrona zdrowia). Pełna kontrola nad bazą to też fundament zgodności z RODO.

Jak wygląda przepływ danych

Najważniejsza różnica względem klasycznego WordPressa polega na tym, że użytkownik końcowy nie odpytuje bazy danych. Payload pracuje w tle jako zaplecze redakcyjne, a Astro wypala gotowy frontend podczas builda.

Praktyczny przepływ wygląda tak:

1. Redaktor edytuje treść w Payload CMS uruchomionym na VPS-ie, potem zmiana trafia do bazy danych, np. PostgreSQL albo MongoDB.
2. Payload wysyła webhook do platformy hostującej frontend i może to być przykładowo Vercel, Netlify albo Cloudflare Pages.
3. Astro uruchamia build, odpytuje Payload przez REST albo GraphQL i pobiera aktualne treści.
4. Wygenerowane HTML, CSS i assety trafiają na CDN.
5. Użytkownik pobiera gotowy plik z CDN-u, a VPS z Payload nie bierze udziału w obsłudze każdej wizyty.

Dzięki temu Payload może działać na małej maszynie, bo jego zadaniem jest obsłużyć panel redakcyjny, API podczas builda, bazę danych i webhooki, a nie cały ruch publiczny.

Jak Astro komunikuje się z Payload CMS

Payload domyślnie wystawia trzy API: REST, GraphQL i lokalne API (to ostatnie działa tylko wewnątrz aplikacji Node, więc dla zewnętrznego frontu Astro używasz REST lub GraphQL).

Zanim Astro zacznie pobierać dane, trzeba zdefiniować w Payload strukturę treści. Payload jest podejściem code-first: kolekcje opisujesz w kodzie, więc schemat da się wersjonować razem z projektem.

Minimalna kolekcja wpisów może wyglądać tak:

import type { CollectionConfig } from 'payload'
 
export const Posts: CollectionConfig = {
  slug: 'posts',
  admin: {
    useAsTitle: 'title',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
    },
    {
      name: 'content',
      type: 'richText',
      required: true,
    },
    {
      name: 'status',
      type: 'select',
      options: [
        { value: 'draft', label: 'Szkic' },
        { value: 'published', label: 'Opublikowany' },
      ],
      defaultValue: 'draft',
      admin: {
        position: 'sidebar',
      },
    },
  ],
}

Taka kolekcja automatycznie wystawia endpoint w formacie https://cms.example.com/api/posts, który Astro może odpytać podczas budowania strony.

Każda kolekcja w Payload automatycznie dostaje swój endpoint REST. Jeśli masz kolekcję posts, jej treść pobierzesz pod adresem w formacie https://cms.example.com/api/posts. W Astro pobierasz to zwykłym fetch() we frontmatterze komponentu:

---
// src/pages/blog/index.astro
const PAYLOAD_API = import.meta.env.PAYLOAD_API // np. https://cms.example.com/api
 
const res = await fetch(`${PAYLOAD_API}/posts?limit=100&sort=-publishedAt`)
const { docs: posts } = await res.json()
---
 
<ul>
  {posts.map((post) => (
    <li>
      <a href={`/blog/${post.slug}`}>
        <h2>{post.title}</h2>
        <p>{post.excerpt}</p>
      </a>
    </li>
  ))}
</ul>

Jeśli wolisz bardziej precyzyjnie kontrolować, jakie pola pobierasz i unikać pobierania zbyt dużej ilości danych (over-fetching), Payload wystawia też GraphQL pod adresem w formacie https://cms.example.com/api/graphql:

---
// fragment frontmattera komponentu .astro
const PAYLOAD_API = import.meta.env.PAYLOAD_API
 
const query = `
  query {
    Posts(limit: 100, sort: "-publishedAt") {
      docs { title slug excerpt publishedAt }
    }
  }
`
 
const res = await fetch(`${PAYLOAD_API}/graphql`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query }),
})
const { data } = await res.json()
const posts = data.Posts.docs
---

Cennym dodatkiem, który powinien docenić każdy zwolennik TypeScriptu jest, że Payload generuje typy ze schematu (payload-types.ts) oraz schemat GraphQL. Możesz je współdzielić, żeby mieć type-safety także po stronie Astro.

Jak aktualizować statyczny frontend po zmianie treści

Statyczna strona nie zmieni się sama w chwili publikacji wpisu w CMS-ie i dlatego potrzebny jest webhook, czyli sygnał wysyłany z Payload do platformy hostującej frontend.

W Payload najczęściej robi się to przez hook afterChange w kolekcji:

hooks: {
  afterChange: [
    async ({ doc, operation }) => {
      const shouldRebuild =
        (operation === 'create' || operation === 'update') &&
        doc.status === 'published'
 
      if (!shouldRebuild) return
 
      await fetch(process.env.FRONTEND_REBUILD_WEBHOOK!, {
        method: 'POST',
      })
    },
  ],
}

W praktyce webhook powinien wskazywać adres deployment hooka z Vercel, Netlify albo Cloudflare Pages. Warto też dodać obsługę błędów, logowanie i zabezpieczenie sekretami, żeby przypadkowe żądanie z internetu nie mogło uruchamiać buildów bez kontroli.

Czego brakuje w tym połączeniu

Na razie nie ma oficjalnego pakietu @payload/astro w stylu @sanity/astro. Oficjalny przewodnik integracji Astro z Payload znajdziesz w dokumentacji Astro pod adresem docs.astro.build/guides/cms/payload. Integrujesz się przez zwykły fetch() na REST lub GraphQL — to działa dobrze i jest proste, ale wymaga trochę więcej grzebania niż gotowa integracja z npm.

Prawdziwa siła Payload to end-to-end TypeScript wewnątrz Next.js. Gdy frontem jest Astro, tracisz tę najgłębszą integrację — Payload staje się zwykłym headless CMS-em odpytywanym po API, a nie częścią tej samej aplikacji. Jeśli kuszą Cię React Server Components i lokalne API bez warstwy HTTP, spójrz w stronę Payload 3.0 i Next.js.

Samodzielne hostowanie to Twoja odpowiedzialność. Backupy, aktualizacje, monitoring i bezpieczeństwo VPS-a są po Twojej stronie. Niestety, taka jest właśnie cena za pełną kontrolę. Coś za coś.

O czym pamiętać na produkcji

Sama integracja przez API to dopiero początek, ponieważ w produkcyjnym projekcie są trzy elementy o jakie musimy zadbać.

Preview dla redaktorów. W modelu SSG wpis jest widoczny publicznie dopiero po buildzie. Jeśli redakcja potrzebuje podglądu szkiców, trzeba przygotować osobną ścieżkę preview: Payload generuje link do ukrytego adresu, a Astro renderuje tę jedną ścieżkę dynamicznie i odpytuje Payload o szkic. To większy zakres niż zwykły statyczny build, ale bez tego praca redakcyjna szybko robi się niewygodna.

Media poza dyskiem VPS-a. Payload potrafi obsługiwać uploady, ale trzymanie zdjęć i PDF-ów wyłącznie na lokalnym dysku serwera jest ryzykowne. Migracja, awaria albo źle wykonany backup mogą oznaczać utratę tych plików, dlatego bezpieczniejszy model to storage zgodny z S3, np. Amazon S3, Cloudflare R2 albo DigitalOcean Spaces, najlepiej z CDN-em dla mediów.

VPS wymaga procesu utrzymania. Będziemy mieli na głowie obowiązki DevOps, więc potrzebne będą aktualizacje systemu, firewall, reverse proxy z certyfikatami TLS, monitoring RAM-u i dysku, automatyczne backupy bazy oraz regularne testowanie przywracania.

Kiedy połączenie Astro i Payload jest najbardziej efektywne?

A tak, mniej ogólnie, a bardziej konkretnie:

1. Duże portale informacyjne posiadające setki czy nawet tysiące artykułów, ogromny ruch, przy niewielkim koszcie serwowania dzięki statyce na CDN-ie.
2. Bazy wiedzy i dokumentacje produktowe, posiadające silnie ustrukturyzowaną treść, którą Payload świetnie modeluje, plus błyskawiczne, statyczne strony, które Google i silniki AI bardzo łatwo i szybko indeksują.
3. Strony korporacyjne z wymogami prawnymi, których dane muszą zostać na miejscu i nie można ich przechowywać w chmurze.

We wszystkich tych przypadkach dostajesz to, co najlepsze z obu światów: wydajność oraz niski koszt statycznego Astro oraz pełną własność danych i brak opłat za skalę po stronie Payload.