Przejdź do treści

Jak połączyć Astro z Sanity CMS krok po kroku

Maciej Sala

Founder StriveLab

15 min czytaniaAktualizacja

Szybka odpowiedź: jak połączyć Astro z Sanity CMS?

  • Zainstaluj @sanity/astro, skonfiguruj w astro.config.mjs i pobieraj treść zapytaniami GROQ przez sanity:client.
  • Minimalny blog potrzebuje schematu wpisu, listy, trasy z getStaticPaths, renderowania Portable Text i webhooka uruchamiającego build.
  • W trybie statycznym treść trafia do HTML-u podczas builda i jest serwowana z CDN.
  • @sanity/astro ma węższy zakres niż next-sanity, więc podgląd na żywo wymaga osobnej konfiguracji.
  • Token dostępu trzymaj tylko po stronie serwera.

Dlaczego warto połączyć Astro z Sanity CMS?

Kombinacja tych dwóch narzędzi jest mocna, ponieważ każde z nich robi coś innego i ich role się nie nakładają. Sanity dostarcza ustrukturyzowaną treść, a Astro zamienia ją w czysty HTML bez zbędnego JavaScriptu.

Sekret tkwi w . Klasyczny framework typu 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, używając do tego celu wyspy (np. menu mobilne czy formularz), które się , podczas gdy reszta strony pozostaje czystym, lekkim HTML-em.

Dla strony opartej na treści to naturalne dopasowanie, ponieważ większość artykułu nie potrzebuje interaktywności. Astro może pobrać dane podczas buildu i zamienić je w gotowe pliki HTML. Dobry wynik nadal zależy od całej strony: obrazów, fontów, CSS-u, skryptów analitycznych, reklam, formularzy i hostingu. Sam wybór frameworka nie zastępuje pomiaru danych terenowych ani testów na urządzeniach mobilnych.

Instalacja i konfiguracja integracji @sanity/astro

Zakładam, że masz już działający projekt Astro; jeśli zaczynasz od zera, skorzystaj z instrukcji utworzenia pierwszego projektu. Komendy integracji wykonuj w katalogu frontendu. Potrzebujesz też projektu Sanity i zbioru danych (w panelu Sanity nazywa się dataset) — ich utworzenie opisuję poniżej przy konfiguracji Studio. Przykłady obrazów korzystają z @sanity/image-url w wersji 2.

Instalacja @sanity/astro i pakietów pomocniczych

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

Code
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:

Code
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 -u Sanity,
  • groq eksportuje defineQuery, dzięki któremu Sanity TypeGen może powiązać zapytanie z wygenerowanym typem wyniku.

Konfiguracja astro.config.mjs i zmiennych środowiskowych

Konfigurację dodajesz w astro.config.mjs:

Code
// astro.config.mjs
import { defineConfig } from 'astro/config'
import react from '@astrojs/react'
import sanity from '@sanity/astro'
import { loadEnv } from 'vite'
 
const { PUBLIC_SANITY_PROJECT_ID, PUBLIC_SANITY_DATASET } = loadEnv(
  process.env.NODE_ENV,
  process.cwd(),
  '',
)
 
export default defineConfig({
  integrations: [
    sanity({
      projectId: PUBLIC_SANITY_PROJECT_ID,
      dataset: PUBLIC_SANITY_DATASET,
      apiVersion: '2026-03-01', // wymagane dla przewidywalnych zapytań
      useCdn: false, // false przy buildzie statycznym i draftach
      perspective: 'published', // bez draftów i nieopublikowanych zmian
    }),
    react(),
  ],
})

W produkcji projectId, dataset i tokeny trzymaj w zmiennych środowiskowych. Sam projectId nie jest sekretem, ale jeden spójny sposób konfiguracji ogranicza ryzyko pomyłek między środowiskiem testowym i produkcyjnym.

Code
PUBLIC_SANITY_PROJECT_ID="YOUR_PROJECT_ID"
PUBLIC_SANITY_DATASET="production"
SANITY_API_READ_TOKEN="token-tylko-do-odczytu"

Prefiks PUBLIC_ stosuj wyłącznie do wartości, które mogą znaleźć się w kodzie przeglądarki. Tokenu nigdy nie oznaczaj jako publiczny. loadEnv() jest tu potrzebne, ponieważ plik astro.config.mjs jest oceniany przed udostępnieniem zmiennych przez import.meta.env. Dla publicznego zbioru danych i zwykłego buildu token nie jest potrzebny; dodajesz go dla prywatnego zbioru danych lub podglądu wersji roboczych i używasz wyłącznie po stronie serwera. Produkcyjne zapytania warto wykonywać z jawną perspektywą published, natomiast podgląd z perspective: 'drafts', tokenem oraz useCdn: false.

Klient sanity:client i prywatny zbiór danych

Integracja wystawia gotowego klienta Sanity jako wirtualny moduł sanity:client, którego importujesz w dowolnym komponencie i nie musisz ręcznie konfigurować połączenia w każdym pliku. Dla TypeScript warto dodać też deklarację typów:

Code
// src/env.d.ts
/// <reference types="astro/client" />
/// <reference types="@sanity/astro/module" />

Dla prywatnego zbioru danych samo wpisanie tokenu do .env nie wystarczy, więc przekaż go do każdego zapytania wymagającego autoryzacji, na przykład we frontmatterze .astro lub w serwerowym module pomocniczym:

Code
import { sanityClient } from 'sanity:client'
 
const token = import.meta.env.SANITY_API_READ_TOKEN
if (!token) throw new Error('Brak SANITY_API_READ_TOKEN dla prywatnego datasetu')
 
const posts = await sanityClient.fetch(
  '*[_type == "post" && defined(slug.current)]{title, "slug": slug.current}',
  {},
  { token, perspective: 'published', useCdn: false },
)

Oczywiście, powyższa zasada dotyczy również autoryzacji zapytań dla listy oraz pojedynczego wpisu – należy w nich zachować filtry daty publikacji. Wspomnianego fragmentu kodu z tokenem autoryzacyjnym pod żadnym pozorem nie wolno importować do komponentów wykonywanych po stronie przeglądarki.

Gdzie uruchomić Sanity Studio: osobny projekt czy trasa w Astro?

Zanim przejdziemy dalej, trzeba rozstrzygnąć, gdzie będzie działać Sanity Studio, czyli aplikacja dla redakcji. Istnieją dwie drogi. Klasycznym rozwiązaniem jest osobny projekt Studio. Uruchamiasz npm create sanity@latest, kreator zakłada projekt w Sanity (dostajesz projectId) i generuje aplikację Studio z folderem na schematy. Wtedy plik sanity/schemas/post.js z następnej sekcji trafia właśnie tam, a Studio wystawiasz osobno (np. npx sanity deploy daje darmowy hosting pod *.sanity.studio).

W osobnym Studio również zarejestruj schemat wpisu: zaimportuj go i dodaj do schema.types w sanity.config.ts albo do tablicy eksportowanej przez wygenerowany plik schemaTypes/index.ts.

Studio osadzone w projekcie Astro. Bardzo wygodne, gdy chcesz mieć wszystko w jednym repozytorium. Integracja @sanity/astro montuje Studio na wskazanej trasie przez opcję studioBasePath (to do tego potrzebny był @astrojs/react):

Code
// astro.config.mjs, fragment integracji
sanity({
  // ...konfiguracja jak wyżej
  studioBasePath: '/admin',
  studioRouterHistory: 'hash', // statyczne Studio bez Presentation Tool
}),

Przy tym wariancie w korzeniu projektu Astro tworzysz jeszcze sanity.config.ts, który definiuje Studio i rejestruje schematy:

Code
// sanity.config.ts
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import post from './sanity/schemas/post'
 
export default defineConfig({
  projectId: 'YOUR_PROJECT_ID',
  dataset: 'production',
  plugins: [structureTool()],
  schema: { types: [post] },
})

Aplikacja wykonuje uwierzytelnione żądania z poziomu przeglądarki, dlatego konieczne jest dodanie adresów frontendu w panelu Sanity w sekcji API → CORS Origins. Dla środowiska lokalnego będzie to zazwyczaj http://localhost:4321, a dla środowiska produkcyjnego – pełna domena serwisu. Opcję Allow credentials należy aktywować wyłącznie dla w pełni kontrolowanych domen.

Aktualna integracja domyślnie wybiera hash history dla output: 'static', a browser history dla output: 'server'; w przykładzie ustawiam hash jawnie. Jeśli w statycznym Studio używasz browser history, odświeżenie podstrony takiej jak /admin/structure może zwrócić 404. Wtedy skonfiguruj na hostingu przekierowanie wewnętrzne /admin/* do /admin albo przełącz Studio na hash history. Przy output: 'server' integracja automatycznie obsługuje trasę dla wszystkich podścieżek. Dla opisanego dalej wariantu Presentation Tool użyj studioRouterHistory: 'browser' oraz serwerowo renderowanego frontendu.

Dla małego bloga wariant osadzony może być najprostszy: panel działa pod /admin, a schematy pozostają w tym samym repozytorium co frontend. Osobne Studio daje natomiast niezależny cykl wdrożeń, osobną domenę i mniejsze powiązanie panelu redakcyjnego z frontendem. Warto je rozważyć nie tylko przy większym zespole, lecz także wtedy, gdy jeden zbiór danych zasila kilka serwisów.

Schemat wpisu blogowego w Sanity

Zanim Astro zacznie pobierać dane, Sanity musi wiedzieć, jak wygląda wpis blogowy. Minimalny model powinien zawierać tytuł, slug, opis, datę publikacji, obraz główny i treść w Portable Text:

Code
// sanity/schemas/post.js
import { defineField, defineType } from 'sanity'
 
export default defineType({
  name: 'post',
  title: 'Wpis',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      title: 'Tytuł',
      type: 'string',
      validation: (rule) => rule.required(),
    }),
    defineField({
      name: 'slug',
      title: 'Slug',
      type: 'slug',
      options: { source: 'title', maxLength: 96 },
      validation: (rule) => rule.required(),
    }),
    defineField({
      name: 'excerpt',
      title: 'Opis SEO',
      type: 'text',
      rows: 3,
      validation: (rule) => rule.required().max(180),
    }),
    defineField({
      name: 'publishedAt',
      title: 'Data publikacji',
      type: 'datetime',
      validation: (rule) => rule.required(),
    }),
    defineField({
      name: 'mainImage',
      title: 'Obraz główny',
      type: 'image',
      options: { hotspot: true },
      fields: [
        defineField({
          name: 'alt',
          title: 'Tekst alternatywny',
          type: 'string',
          validation: (rule) => rule.required(),
        }),
      ],
    }),
    defineField({
      name: 'body',
      title: 'Treść',
      type: 'array',
      of: [
        { type: 'block' },
        {
          type: 'image',
          options: { hotspot: true },
          fields: [
            defineField({
              name: 'alt',
              title: 'Tekst alternatywny',
              type: 'string',
              validation: (rule) => rule.required(),
            }),
          ],
        },
      ],
      validation: (rule) => rule.required(),
    }),
  ],
})

To prosty schemat wystarczający do uruchomienia bloga. Przed produkcją ustal jednak model SEO i redakcji: autora, kategorie, kanoniczny URL, tytuł oraz opis Open Graph, zasady przekierowania po zmianie sluga i relacje między wersjami językowymi. Nie dodawaj wszystkich możliwych pól „na zapas”, ale zaprojektuj te wpływające na publiczny adres i migrację treści przed pierwszą publikacją.

Jak pobierać dane z Sanity CMS w Astro za pomocą GROQ

Tu wkracza , czyli język zapytań Sanity, który jest trochę jak dla grafu dokumentów JSON: filtrujesz, sortujesz, robisz projekcje i złączenia w jednym zapytaniu. Sanity wystawia też , jeśli masz takie preferencje, ale GROQ jest natywny i zwykle zwięźlejszy. Wybór należy do Ciebie.

Przykłady korzystają z własnego BaseLayout.astro. Jeśli jeszcze go nie masz, utwórz minimalną wersję:

Code
---
// src/layouts/BaseLayout.astro
const { title, description } = Astro.props
---
 
<!doctype html>
<html lang="pl">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{title}</title>
    {description && <meta name="description" content={description} />}
  </head>
  <body><slot /></body>
</html>

W Astro pobierasz dane bezpośrednio we komponentu, czyli w bloku między ---, który wykonuje się na serwerze podczas buildu i nigdy nie trafia do przeglądarki:

Code
---
// 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.current) &&
    defined(publishedAt) &&
    dateTime(publishedAt) <= dateTime(now())
  ] | 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ę tak: weź opublikowane dokumenty typu post, które mają slug i datę publikacji nieprzekraczającą bieżącej chwili, posortuj je od najnowszego i zwróć tylko potrzebne pola. Cała ta logika wykonuje się raz podczas buildu, a użytkownik dostaje gotowy HTML. Filtr daty jest ważny, ponieważ dokument może być opublikowany w Sanity, ale zaplanowany do pokazania dopiero później.

W SSG sam filtr nie uruchomi jednak nowego buildu o godzinie zapisanej w publishedAt. Jeśli publikujesz dokument dziś z datą ustawioną na jutro, dzisiejszy webhook zbuduje stronę bez tego wpisu, a jutro nie pojawi się nowe zdarzenie w Sanity. W związku z powyższym zaplanowane publikacje wymagają więc cyklicznego buildu na hostingu, osobnego harmonogramu wyzwalającego wdrożenie o właściwej porze albo trasy renderowanej na żądanie.

Typowanie zapytań przez Sanity TypeGen

Samo wywołanie defineQuery nie powoduje jeszcze automatycznego wygenerowania typów. Zapytania należy umieścić w osobnym pliku z rozszerzeniem .ts, przeprowadzić proces ekstrakcji schematu oraz generowania typów, a powstały plik uwzględnić w sekcji include pliku konfiguracyjnego tsconfig.json:

Code
// src/lib/queries.ts
import { defineQuery } from 'groq'
 
export const POSTS_QUERY = defineQuery(`
  *[
    _type == "post" &&
    defined(slug.current) &&
    defined(publishedAt) &&
    dateTime(publishedAt) <= dateTime(now())
  ] | order(publishedAt desc) {
    _id,
    title,
    "slug": slug.current,
    excerpt,
    publishedAt
  }
`)

Komendy uruchom w katalogu zawierającym sanity.config.ts. Dla Studio osadzonego będzie to katalog projektu Astro:

Code
npx sanity schema extract
npx sanity typegen generate

Przy osobnym Studio uruchom sanity schema extract w jego katalogu, a wygenerowany schema.json udostępnij frontendowi, np. kopiując go do katalogu głównego projektu Astro. We frontendzie zainstaluj CLI przez npm install --save-dev sanity i dodaj konfigurację:

Code
// sanity.cli.ts w projekcie Astro z osobnym Studio
import { defineCliConfig } from 'sanity/cli'
 
export default defineCliConfig({
  typegen: {
    path: './src/**/*.{ts,tsx,js,jsx}',
    schema: './schema.json',
    generates: './sanity.types.ts',
  },
})

Następnie uruchom npx sanity typegen generate we frontendzie. Po zmianach schematu ponów ekstrakcję i przekazanie pliku; po zmianach zapytań ponów generowanie typów. W monorepo możesz zamiast kopiowania wskazać ścieżkę do pliku w katalogu Studio.

We frontmatterze listy wpisów zastąp zapytanie tekstowe stałą z pliku .ts, aby klient mógł wykorzystać wygenerowany typ wyniku:

Code
import { sanityClient } from 'sanity:client'
import { POSTS_QUERY } from '../../lib/queries'
 
const posts = await sanityClient.fetch(POSTS_QUERY)

Dla prywatnego zbioru danych przekaż również token jako opcję trzeciego argumentu fetch(), zgodnie z wcześniejszym przykładem.

TypeGen ogranicza ręczne dublowanie schematu, ale nie zastępuje obsługi wartości opcjonalnych. Build powinien nadal przerwać się czytelnym błędem, jeśli wpis nie ma pól wymaganych przez frontend.

Dynamiczne strony wpisów w Astro z getStaticPaths

Lista wpisów to dopiero połowa bloga, podczas gdy druga połowa to dynamiczna trasa src/pages/blog/[slug].astro, która podczas buildu generuje osobną stronę dla każdego sluga z Sanity:

Code
---
// src/pages/blog/[slug].astro
import { sanityClient } from 'sanity:client'
import ArticleBody from '../../components/ArticleBody.astro'
import BaseLayout from '../../layouts/BaseLayout.astro'
import { urlFor } from '../../lib/sanityImage'
 
export async function getStaticPaths() {
  const posts = await sanityClient.fetch(
    `*[
      _type == "post" &&
      defined(slug.current) &&
      defined(publishedAt) &&
      dateTime(publishedAt) <= dateTime(now())
    ] {
      title,
      "slug": slug.current,
      excerpt,
      publishedAt,
      body[]{
        ...,
        _type == "image" => {
          asset->,
          alt
        }
      },
      mainImage {
        ...,
        alt
      }
    }`
  )
 
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },
  }))
}
 
const { post } = Astro.props
 
const imageUrl = post.mainImage
  ? urlFor(post.mainImage).width(1200).height(630).fit('crop').auto('format').url()
  : null
---
 
<BaseLayout title={post.title} description={post.excerpt}>
  <article>
    <h1>{post.title}</h1>
 
    {imageUrl && (
      <img
        src={imageUrl}
        alt={post.mainImage?.alt ?? ''}
        width="1200"
        height="630"
        loading="eager"
        fetchpriority="high"
      />
    )}
 
    <ArticleBody value={post.body} />
  </article>
</BaseLayout>

W tym wariancie getStaticPaths() pobiera wszystkie wpisy jednym zapytaniem GROQ i przekazuje je do stron przez props. Eliminuje to osobne żądanie dla każdego sluga, ale zwiększa rozmiar pojedynczej odpowiedzi oraz użycie pamięci podczas buildu. Dla małego i średniego bloga jest to rozsądny kompromis. Przy dużych treściach porównaj go z pobraniem samych slugów i osobnym zapytaniem parametryzowanym dla każdej strony albo z przetwarzaniem danych partiami.

Niezależnie od wybranego wariantu unikaj bezpośredniej interpolacji Astro.params.slug w zapytaniach GROQ. Zamiast tego skorzystaj z parametru $slug i przekaż { slug } jako drugi argument funkcji fetch(). Klient Sanity przekazuje parametry oddzielnie od treści zapytania, co skutecznie chroni strukturę zapytania przed niepożądaną ingerencją wartości pochodzących z adresu URL.

Jak renderować Portable Text i obrazy z Sanity w Astro

Treść z Sanity nie jest Markdownem ani HTML-em, ponieważ domyślny edytor zapisuje ją jako Portable Text, czyli strukturalny JSON. Dzięki temu treść jest przenośna, ale musisz ją wyrenderować po stronie Astro.

Najprostszy wariant to komponent PortableText:

Code
---
import { PortableText } from 'astro-portabletext'
 
const body = post.body
---
 
<PortableText value={body} />

Ten wariant wystarcza tylko dla standardowych bloków tekstowych. Schemat z tego artykułu dopuszcza również obraz wewnątrz body, dlatego trzeba przypisać typ image do własnego komponentu:

Code
---
// src/components/ArticleBody.astro
import { PortableText } from 'astro-portabletext'
import SanityImage from './SanityImage.astro'
 
const components = {
  type: {
    image: SanityImage,
  },
}
---
 
<PortableText value={Astro.props.value} components={components} />

Komponent obrazu odbiera blok Portable Text jako node. W tym przykładzie wszystkie warianty mają proporcje 16:9: te same proporcje przekazujesz do transformacji CDN i atrybutów HTML, aby kadrowanie w Studio nie powodowało rozbieżności wymiarów:

Code
---
// src/components/SanityImage.astro
import { urlFor } from '../lib/sanityImage'
 
const { node } = Astro.props
const width = 800
const height = 450
---
 
{node.asset && (
  <img
    src={urlFor(node).width(width).height(height).fit('crop').auto('format').url()}
    srcset={[480, 800, 1200]
      .map((size) => `${urlFor(node).width(size).height(Math.round(size * height / width)).fit('crop').auto('format').url()} ${size}w`)
      .join(', ')}
    sizes="(min-width: 900px) 800px, calc(100vw - 32px)"
    alt={node.alt ?? ''}
    width={width}
    height={height}
    loading="lazy"
    decoding="async"
  />
)}

Tą samą metodą obsłużysz bloki kodu, filmy i linki wewnętrzne. Projekcja GROQ musi zwracać dane wymagane przez komponent. W głównym przykładzie robi to body[]{..., _type == "image" => {asset->, alt}}, dzięki czemu dostępne są również wymiary zasobu. Nieznany typ bloku powinien być widoczny w testach, zamiast po cichu znikać z opublikowanego artykułu.

Z kolei dla obrazów użyj @sanity/image-url, żeby korzystać z transformacji Sanity CDN i nie wstawiać surowych plików bez kontroli rozmiaru:

Code
// src/lib/sanityImage.js
import { createImageUrlBuilder } from '@sanity/image-url'
import { sanityClient } from 'sanity:client'
 
const builder = createImageUrlBuilder(sanityClient)
 
export function urlFor(source) {
  return builder.image(source)
}

Wtedy w komponencie możesz wygenerować obraz dopasowany do layoutu:

Code
<img
  src={urlFor(post.mainImage).width(1200).height(630).fit('crop').auto('format').url()}
  alt={post.mainImage.alt ?? ''}
  width="1200"
  height="630"
/>

Dla obrazu wyświetlanego w różnych szerokościach dodaj srcset i sizes, aby telefon nie pobierał pliku przygotowanego dla dużego ekranu. Również tutaj przykład zachowuje docelowe proporcje 16:9:

Code
<img
  src={urlFor(image).width(800).height(450).fit('crop').auto('format').url()}
  srcset={[480, 800, 1200]
    .map((width) => `${urlFor(image).width(width).height(Math.round(width * 9 / 16)).fit('crop').auto('format').url()} ${width}w`)
    .join(', ')}
  sizes="(min-width: 900px) 800px, calc(100vw - 32px)"
  alt={image.alt}
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>

Przy zachowaniu stałych proporcji nie ma konieczności odczytywania wymiarów zasobu. Aby uwzględnić proporcje obrazu zdefiniowane przez redaktora, należy pobrać właściwość asset->metadata.dimensions oraz uwzględnić parametry kadrowania (crop): szerokość po przycięciu wynosi width * (1 - crop.left - crop.right), natomiast wysokość określa wzór height * (1 - crop.top - crop.bottom). Brakujące wartości przycięcia należy traktować jako zero. Wymiary w kodzie HTML powinny precyzyjnie odpowiadać proporcjom wynikowej grafiki, co umożliwia zarezerwowanie właściwej przestrzeni i skuteczne ograniczenie wskaźnika CLS. Obrazu LCP nie ładuj leniwie tylko pozostaw loading="eager" oraz fetchpriority="high", ale nie stosuj tych atrybutów do wszystkich ilustracji w treści - ma to kluczowe znaczenie dla Core Web Vitals. W sytuacji, gdy umieścisz na stronie oryginalny obraz o szerokości 4000 px wprost z biblioteki mediów, witryna oparta na Astro co prawda nadal będzie działać sprawnie, jednak wskaźnik LCP może wyraźnie ucierpieć przez zbyt ciężki zasób.

Jeśli zależy Ci na wysokich pozycjach w wyszukiwarce Google, warto zadbać również o pełne SEO. Oficjalna integracja @astrojs/sitemap wymaga ustawienia produkcyjnego adresu w opcji site:

Code
import sitemap from '@astrojs/sitemap'
 
export default defineConfig({
  site: 'https://example.com',
  integrations: [sanity(/* ... */), react(), sitemap()],
})

Przy buildzie integracja generuje sitemap-index.xml oraz co najmniej jeden plik, na przykład sitemap-0.xml. Obejmuje również dynamiczne strony utworzone przez getStaticPaths(), ale nie potrafi automatycznie odkryć dynamicznych tras renderowanych wyłącznie w SSR. Link kanoniczny i tagi Open Graph generuj w layoutcie z pól wpisu. Obraz OG masz już gotowy dzięki transformacjom urlFor w rozmiarze 1200×630.

SSG czy SSR: który tryb renderowania wybrać dla Astro z Sanity?

Wybór sposobu renderowania wpływa na to, kiedy treść z Sanity trafia na stronę:

(domyślny) oznacza, że każde zapytanie GROQ wykonuje się raz, podczas buildu, 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ą z Sanity). To wybór dla większości blogów i stron firmowych, ponieważ jest najszybszy i najtańszy.

Renderowanie na żądanie () oznacza, że strona może zostać wyrenderowana podczas żądania. Nie gwarantuje to jednak natychmiastowej świeżości: wynik nadal może przechodzić przez cache Sanity, frameworka lub hostingu. Potrzebujesz adaptera zgodnego z platformą. Po SSR sięgasz przy podglądzie wersji roboczych, treści zależnej od plików cookie albo personalizacji, a zasady cache ustalasz osobno dla każdej z tych potrzeb.

W prostym modelu możesz zachować publiczny blog jako SSG i utworzyć osobne, serwerowe trasy podglądu z export const prerender = false. Aktualny oficjalny przewodnik Sanity po pełnym Visual Editing w Astro 7 stosuje jednak output: 'server', ponieważ ta sama trasa odczytuje przy każdym żądaniu ciasteczko trybu podglądu i wybiera perspektywę treści. Jeśli część tras nie potrzebuje tego mechanizmu, możesz prerenderować je jawnie przez export const prerender = true.

Przy okazji domknij regułę useCdn: dla zapytań wykonywanych w buildzie zostaw false, aby pobrać najświeższy opublikowany stan. Dla tras SSR z publiczną treścią zwykle ustaw true, natomiast dla perspektywy drafts zawsze używaj tokenu i useCdn: false. Token powinien mieć minimalne uprawnienia, na przykład Viewer, i nigdy nie może trafić do przeglądarki.

Visual Editing wymaga również skonfigurowania Presentation Tool, podania adresu Studio na potrzeby kodowania stega, przygotowania bezpiecznej ścieżki włączającej tryb podglądu oraz dodania frontendu do listy CORS z obsługą poświadczeń. To pełnoprawna funkcja produkcyjna, a nie pojedyncza przełączana flaga w integracji.

Automatyczna przebudowa strony po publikacji: webhook z Sanity

Musisz pamiętać, że statyczna strona nie zaktualizuje się sama po kliknięciu „Publish” w Sanity. Potrzeba sygnału, który uruchomi nowy build i najprostszym jest wariant webhook z Sanity do platformy hostingowej:

  1. W panelu Sanity wejdź w projekt i sekcję API / Webhooks.
  2. Utwórz webhook z możliwie wąskim filtrem, na przykład _type == "post".
  3. Jako adres podaj build hook z Vercela, Netlify albo Cloudflare Pages.
  4. Zaznacz techniczne zdarzenia Create, Update i Delete: obejmują one pierwszą publikację, kolejne publikacje oraz wycofanie publikacji.
  5. Nie włączaj zdarzeń dla wersji roboczych ani wersji z wydań, jeśli każde naciśnięcie klawisza nie ma uruchamiać buildu. Domyślnie są pomijane.
  6. Sprawdź w logu prób, czy platforma zwraca kod z zakresu 2xx i rzeczywiście rozpoczyna wdrożenie.

Adres build hooka jest sekretem dającym możliwość uruchamiania wdrożeń, dlatego nie umieszczaj go w repozytorium ani publicznych logach. Jeśli webhook trafia najpierw do własnego endpointu, zweryfikuj podpis przy użyciu sekretu Sanity i obsłuż nagłówek idempotency-key, ponieważ dostarczenie ma semantykę co najmniej raz i może zostać powtórzone. Przy serii publikacji warto zastosować kolejkę lub opóźnione grupowanie zdarzeń, aby kilka zmian nie uruchamiało konkurencyjnych buildów.

Ten mechanizm domyka podstawowy przepływ, ale publikacja nie kończy się na wysłaniu webhooka i dlatego monitoruj nieudane buildy, czas od publikacji do dostępności nowej wersji i stan ostatniego wdrożenia. Cały czas zachowaj możliwość ręcznego przebudowania serwisu oraz wycofania wadliwej publikacji.

Produkcyjna lista kontrolna Astro i Sanity

Przed uruchomieniem bloga sprawdź cały przepływ, a nie tylko lokalne renderowanie pojedynczego wpisu:

  1. Dostęp do danych: produkcja używa perspektywy published, token podglądu pozostaje po stronie serwera, a zbiór danych ma świadomie wybrany tryb publiczny lub prywatny.
  2. Integralność treści: schemat wymaga kluczowych pól, zapytania pomijają przyszłe publikacje, a brak dokumentu lub nieprawidłowy slug kończy się kontrolowanym 404.
  3. Portable Text: każdy niestandardowy blok i adnotacja mają komponent, test oraz bezpieczne zachowanie awaryjne.
  4. Obrazy: grafiki mają tekst alternatywny, wymiary, srcset, sizes i odpowiednią strategię ładowania; obraz LCP nie jest ładowany leniwie.
  5. SEO po zmianie sluga: stary adres otrzymuje przekierowanie 301, link kanoniczny wskazuje aktualną stronę, a sitemapę generujesz dopiero z publicznych dokumentów.
  6. Publikacja: webhook ma wąski filtr, logi prób i monitoring buildu; zespół zna procedurę ręcznego wdrożenia oraz wycofania.
  7. Podgląd: Visual Editing nie ujawnia tokenu ani wersji roboczych, CORS dopuszcza tylko wymagane źródła, a trasa aktywująca tryb podglądu weryfikuje sekret.

Na koniec opublikuj wpis testowy, zaktualizuj go i usuń. Sprawdź stronę listy, stronę artykułu, sitemapę, wynik 404 oraz wdrożenie po każdej operacji. Test pełnego cyklu wykrywa inne błędy niż samo uruchomienie astro build.

Ograniczenia integracji Astro z Sanity CMS

@sanity/astro ma inny zakres niż next-sanity i nie udostępnia identycznego modelu integracji. Integracja ta nie przypomina prostego przełącznika typu włącz podgląd na żywo. Pakiet next-sanity ściśle współpracuje z Next.js, korzystając z Live Content API oraz mechanizmów rewalidacji cache. Z kolei w Astro standardowy, najprostszy model opiera się na statycznym buforze i webhookach. Choć Visual Editing jest tam jak najbardziej możliwy, wymaga zupełnie osobnej konfiguracji: tokenu dostępu do wersji roboczych, specjalnego trybu podglądu, narzędzia Presentation Tool, kodowania stega oraz tras działających po stronie serwera.

Dla bloga czy strony firmowej nie jest to większy problem, ponieważ publikacja z kilkudziesięciosekundowym opóźnieniem po buildzie jest akceptowalna. Redakcja może widzieć zmiany po edycji również w Astro: standardowy mechanizm Visual Editing odświeża całą stronę podglądu i pobiera aktualną treść z serwera. Nie jest to jednak odpowiednik defineLive / <SanityLive /> z Next.js, który aktualizuje treść bez pełnego przeładowania strony. Jeśli potrzebujesz takiego modelu aktualizacji albo budujesz frontend z rozbudowaną logiką aplikacyjną, warto rozważyć Next.js z Payload albo Sanity z Next.js.

Gotową stronę w Astro z panelem Sanity przygotowuję w ramach stron internetowych w Astro.

Ultraszybkie projekty, łączące lekkość ze skalowalnością.
Astro

Często zadawane pytania

Czy Astro z Sanity nadaje się do dużego bloga?

Tak. W trybie statycznym Astro pobiera treść podczas buildu i serwuje gotowy HTML. Przy setkach lub tysiącach wpisów trzeba jednak kontrolować rozmiar projekcji GROQ, czas i pamięć buildu, częstotliwość publikacji oraz limity platformy. Czasem lepsze są zapytania stronicowane, renderowanie na żądanie wybranych tras albo podział serwisu na mniejsze sekcje.

Czym jest GROQ i czy trudno się go nauczyć?

GROQ (Graph-Relational Object Queries) to język zapytań Sanity, projektowany pod grafy dokumentów JSON. Ma łagodną krzywą uczenia i szybko staje się produktywny, bo w jednym zapytaniu robisz filtrowanie, sortowanie, projekcje i złączenia, które w REST wymagałyby kilku osobnych żądań. Sanity wystawia też GraphQL, jeśli wolisz.

Czy w Astro można osadzić Sanity Studio?

Tak. Integracja @sanity/astro pozwala zamontować Sanity Studio na wybranej trasie (np. /admin) za pomocą opcji studioBasePath. Wymaga to dodatkowo @astrojs/react. Dzięki temu panel edycyjny i strona żyją w jednym projekcie.

Czy zmiany w Sanity pojawiają się na stronie od razu?

W trybie statycznym nie, ponieważ treść aktualizuje się przy najbliższej przebudowie, zwykle wyzwalanej webhookiem z Sanity po zapisaniu zmiany. W trybie serwerowym (SSR) strona ponownie pobiera treść przy żądaniu, ale jej świeżość nadal zależy od ustawień cache Sanity i hostingu. Sanity ma Visual Editing dla Astro, ale wymaga osobnej konfiguracji: trybu podglądu, tokenów, Presentation Tool i serwerowo renderowanego podglądu.

Co to jest architektura wysp (Astro Islands) i dlaczego jest ważna dla wydajności?

Architektura wysp polega na tym, że Astro domyślnie renderuje całą stronę do statycznego HTML bez JavaScriptu. Interaktywność dodajesz tylko punktowo jako izolowane wyspy komponentów, które się hydratują w przeglądarce. Dzięki temu strona z treścią ładuje się błyskawicznie, bo przeglądarka nie musi parsować i wykonywać kilobajtów JS przy każdym wejściu.

O autorze

Maciej Sala

Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną
LH.pl – Hosting Mango

Biblioteka wiedzy na temat Astro

Czytaj dalej

Zobacz więcej wpisów
Jak połączyć Next.js z Sanity CMS krok po kroku

Redaktor powinien móc otworzyć szkic, zobaczyć zmianę tytułu i kliknąć tekst, aby wrócić do właściwego pola w CMS-ie. W Sanity z Next.js te czynności wymagają połączenia modelu treści, zapytań, podglądu i nakładek edycji. Zbudujemy mały blog, w którym lista, artykuł i metadane korzystają z tej samej ścieżki pobierania danych, a Studio działa pod adresem /studio.

Maciej Sala

Maciej Sala

Founder StriveLab

Payload CMS czy Sanity: który headless CMS wybrać?

Payload i Sanity potrafią obsłużyć ten sam katalog treści, lecz przenoszą ciężar projektu w zupełnie inne miejsce. Payload oddaje zespołowi kod, bazę i odpowiedzialność za produkcję. Sanity dostarcza zarządzany Content Lake oraz rozbudowane środowisko współpracy, ale wiąże system z limitami i modelem usługi. Dobre porównanie nie kończy się na ekranie edytora. Musi objąć dzień publikacji, awarię, zmianę schematu, rachunek przy wzroście oraz możliwość wyprowadzenia danych.

Maciej Sala

Maciej Sala

Founder StriveLab

Headless CMS dla Astro: porównanie Sanity, Storyblok i Strapi

Markdown w plikach projektu działa sprawnie, dopóki treść piszą osoby, które swobodnie pracują w Git. W sytuacji, kiedy klient chce sam zmienić cennik, a redaktor poprawia nagłówek w piątek po południu, repozytorium przestaje być wygodnym CMS-em. Wtedy najlepszy będzie headless CMS, czyli panel dla redakcji i API dla Astro.

Maciej Sala

Maciej Sala

Founder StriveLab

LH.pl – Cloud Server 1C4G