Jak połączyć Astro z Sanity CMS? Przewodnik po ultra-szybkim blogu

Dlaczego Astro i Sanity działają tak dobrze razem

Każde z tych narzędzi robi dokładnie jedną rzecz znakomicie, a ich role się nie nakładają. Sanity dostarcza ustrukturyzowaną treść, a Astro zamienia ją w czysty HTML — bez zbędnego JavaScriptu.

Sekret tkwi w architekturze wyspArchitektura wysp (Islands Architecture) to wzorzec, w którym większość strony jest statycznym HTML-em, a interaktywne fragmenty hydratują się jako niezależne wyspy. (Astro Islands). Klasyczny framework typu SPASPA (Single Page Application) to aplikacja webowa, w której cała strona renderuje się i działa po stronie przeglądarki w jednym dokumencie HTML — typowe podejście Reacta, Vue czy Angulara bez SSR. wysyła do przeglądarki cały JavaScript potrzebny do zbudowania strony, nawet jeśli to zwykły artykuł, który nic nie robi po załadowaniu. Astro odwraca tę logikę: domyślnie renderuje wszystko do statycznego HTML-a i nie wysyła żadnego JavaScriptu. Interaktywność dokładasz tylko punktowo — jako wyspy (np. menu mobilne czy formularz), które się nawadniająHydratacja to dołączenie JavaScriptu do wyrenderowanego HTML, dzięki czemu statyczny komponent staje się interaktywny. (hydrate), podczas gdy reszta strony pozostaje czystym, lekkim HTML-em.

Dla strony contentowej to idealne dopasowanie. Treść z Sanity i tak nie potrzebuje interaktywności — to tekst, obrazy, nagłówki. Astro pobiera te dane raz, podczas builda, i wypala je w gotowe pliki HTML. Efekt: strona ładuje się błyskawicznie, a Lighthouse pokazuje wyniki w okolicach 100/100 praktycznie z pudełka, bo nie ma czego ładować poza HTML-em i CSS-em.

Jak zainstalować integrację Astro z Sanity

Sanity utrzymuje oficjalną integrację @sanity/astro, więc nie wymyślasz koła na nowo. Instalacja to jedna komenda:

npx astro add @sanity/astro @astrojs/react

@astrojs/react jest potrzebny, jeśli chcesz korzystać z wizualnej edycji albo osadzić Sanity Studio na trasie w projekcie Astro. Warto przy okazji dograć pakiety pomocnicze:

npm install astro-portabletext @sanity/image-url groq

• astro-portabletext — renderuje Portable Text (format tekstu sformatowanego z Sanity) do HTML-a
• @sanity/image-url — buduje URL-e obrazów z transformacjami z CDNCDN, czyli Content Delivery Network, to rozproszona sieć serwerów dostarczająca zasoby z węzła najbliższego użytkownikowi; CDN do obrazów dodatkowo transformuje je w locie.-u Sanity
• groq — eksportuje defineQuery do typowanych zapytań

Konfigurację dodajesz w astro.config.mjs:

// astro.config.mjs
import { defineConfig } from 'astro/config'
import sanity from '@sanity/astro'
 
export default defineConfig({
  integrations: [
    sanity({
      projectId: 'YOUR_PROJECT_ID',   // znajdziesz na sanity.io/manage
      dataset: 'production',
      apiVersion: '2026-03-01',        // wymagane dla przewidywalnych zapytań
      useCdn: false,                   // false przy buildzie statycznym i draftach
    }),
  ],
})

Integracja wystawia gotowego klienta Sanity jako wirtualny moduł sanity:client, którego importujesz w dowolnym komponencie. Nie musisz ręcznie konfigurować połączenia w każdym pliku.

Jak pobierać dane z Sanity w Astro przez GROQ

Tu wkracza GROQGROQ to język zapytań Sanity służący do pobierania i filtrowania treści z datasetu. — język zapytań Sanity. Jest trochę jak SQL dla grafu dokumentów JSON: filtrujesz, sortujesz, robisz projekcje i joiny w jednym zapytaniu. (Sanity wystawia też GraphQLGraphQL to język zapytań do API, w którym klient precyzyjnie określa, jakie pola chce pobrać — zamiast sztywnych endpointów REST zwracających całe obiekty., jeśli wolisz, ale GROQ jest natywny i zwykle zwięźlejszy.)

W Astro pobierasz dane bezpośrednio we frontmatterzeFrontmatter to blok metadanych na początku pliku Markdown/MDX, zapisany zwykle w YAML między liniami ---. komponentu — czyli w bloku między ---, który wykonuje się na serwerze podczas builda i nigdy nie trafia do przeglądarki:

---
// src/pages/blog/index.astro
import { sanityClient } from 'sanity:client'
import BaseLayout from '../../layouts/BaseLayout.astro'
 
const posts = await sanityClient.fetch(
  `*[_type == "post" && defined(slug)] | order(publishedAt desc) {
    title,
    "slug": slug.current,
    excerpt,
    publishedAt
  }`
)
---
 
<BaseLayout title="Blog">
  <h1>Blog</h1>
  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/blog/${post.slug}`}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </a>
      </li>
    ))}
  </ul>
</BaseLayout>

To zapytanie GROQ czyta się prosto: weź wszystkie dokumenty typu post, które mają sluga, posortuj od najnowszego i zwróć tylko te cztery pola. Cała ta logika wykonuje się raz, podczas builda — użytkownik dostaje gotowy HTML.

Statycznie czy serwerowo? Dwa tryby renderowania

Astro ma dwa tryby, a wybór wpływa na to, kiedy treść z Sanity trafia na stronę:

Tryb statycznySSG (Static Site Generation) to generowanie kompletnego HTML podczas budowania strony. Gotowe pliki serwujesz z CDN bez renderowania na żądanie — najszybszy i najtańszy model dla treści, która nie zmienia się przy każdej wizycie. (domyślny) — każde zapytanie GROQ wykonuje się raz, podczas builda, a strony serwowane są jako statyczne pliki. Idealny, gdy treść nie zmienia się co minutę i możesz pozwolić sobie na chwilę zwłoki między publikacją a przebudową (zwykle wyzwalaną webhookiemWebhook to automatyczne powiadomienie HTTP wysyłane przez Stripe do Twojej aplikacji po wystąpieniu zdarzenia, np. udanej płatności. z Sanity). To wybór dla większości blogów i stron firmowych — najszybszy i najtańszy.

Tryb serwerowySSR, czyli Server-Side Rendering, to generowanie HTML na serwerze przy żądaniu — komponent client:only je pomija i renderuje się wyłącznie w przeglądarce. (SSR) — strony renderują się na każde żądanie, więc zapytania GROQ działają w czasie rzeczywistym i zmiany widać natychmiast, bez przebudowy. Potrzebujesz do tego adaptera pod swój hosting (np. Vercel). Sięgasz po niego, gdy potrzebujesz podglądu draftów, wizualnej edycji albo treści personalizowanej.

Czego ta integracja NIE potrafi — uczciwie

@sanity/astro jest lżejsze niż next-sanity i celowo nie ma kilku jego funkcji.

Nie ma odpowiednika Live Content API — w Next.js next-sanity daje automatyczne aktualizacje treści na żywo i rewalidację cacheCache przechowuje gotową odpowiedź lub zasób, żeby nie generować go od zera przy każdym wejściu użytkownika.. W Astro tego nie ma out of the box: aktualizacje wymagają przebudowy (tryb statyczny) albo odświeżenia strony (SSR). Nie ma też wbudowanej rewalidacji cache zintegrowanej z frameworkiem.

Dla bloga czy strony firmowej to zwykle nie problem. Jeśli jednak budujesz coś, gdzie liczy się natychmiastowość i interaktywność na poziomie aplikacji, warto rozważyć Next.js z Payload zamiast Astro.