Astro 6 — przewodnik po nowościach: Cloudflare Workers, Live Content Collections, Fonts API i CSP

Astro 6 to największa aktualizacja Astro od lat. Przejście z gałęzi 5.x na 6.x zmienia architekturę lokalnego środowiska programistycznego — przebudowany serwer deweloperski, głębsza integracja z Cloudflare Workers, stabilne Live Content Collections, wbudowane zarządzanie fontami i obsługa Content Security Policy. Te wszystkie zmiany wyznaczają nowe standardy pracy.

Kontekst — Cloudflare i Astro razem

16 stycznia 2026 roku Cloudflare przejął The Astro Technology Company. Framework pozostał na licencji MIT i nadal działa niezależnie od platformy — Netlify, Vercel, AWS, własny VPS. Z Astro 6 przyszła głęboka integracja z ekosystemem Cloudflare, która istotnie zmienia sposób lokalnej pracy z frameworkiem.

Dane pokazują wyraźny podział rynku: Vercel + Next.js kontra Cloudflare + Astro. Jeśli interesuje Cię szersza analiza różnic między tymi technologiami, szczegółowo opisałem to w artykule Astro.js vs Next.js — które narzędzie wybrać w 2026 roku?.

Nowy serwer programistyczny — workerd jako środowisko uruchomieniowe

Największa techniczna zmiana w Astro 6 to przebudowa astro dev i jest to bardzo znacząca zmiana. Wcześniej lokalny serwer działał w Node.js, a produkcja w Cloudflare Workers, Deno albo Bun. Ten rozdźwięk był architektoniczną pułapką, która rodziła najdroższe błędy: te z kategorii „u mnie działało”, i w praktyce eliminował sensowność testów lokalnych.

Astro 6 rozwiązał ten problem, ponieważ dzięki Vite Environment API kod uruchamiany lokalnie działa w dokładnie tym samym środowisku co na produkcji. Dla użytkowników infrastruktury Cloudflare oznacza to, że astro dev startuje bezpośrednio w workerd — tym samym silniku JavaScript, który napędza Cloudflare Workers. Masz pełen dostęp do Durable Objects, KV Namespaces, R2 Storage, Workers Analytics Engine i D1, bez żadnych zaślepek.

# Inicjalizacja Astro 6 z adapterem Cloudflare
npm create astro@latest
npx astro add cloudflare
 
# Lokalny serwer działający na workerd
npm run dev

Kluczem do sukcesu jest eliminacja zaślepek. Nie ma już Astro.locals.runtime workaround, nie ma bibliotek symulujących Cloudflare lokalnie. Jeśli korzystasz z KV, R2 albo Durable Objects — pracujesz na nich bezpośrednio, z pełnym HMR.

Live Content Collections — dynamiczne treści bez przebudowywania projektu

Klasyczny mechanizm Content Collections bazował wyłącznie na etapie budowania — cała zawartość ładowana i weryfikowana podczas generowania statycznych plików. Dla blogów i dokumentacji to idealne rozwiązanie. Dla danych zmieniających się w czasie rzeczywistym — stanów magazynowych, aktualnych cen, spersonalizowanych danych użytkownika — był to mur techniczny.

Astro 6 burzy ten mur, wprowadzając Live Content Collections. Ten sam typowany system pracy z treścią, ale z loaderami danych wykonywanymi na żądanie w czasie działania aplikacji. Schematy Zod i autouzupełnianie w edytorze zostają — zmienia się tylko źródło danych, które odpytywane jest przy każdym żądaniu użytkownika.

// src/live.config.ts
import { defineLiveCollection } from 'astro:content'
import { z } from 'astro/zod'
import { productsLoader } from './loaders/products'
 
const products = defineLiveCollection({
  loader: productsLoader({
    apiUrl: 'https://api.example.com/products',
  }),
  schema: z.object({
    id: z.string(),
    name: z.string(),
    price: z.number(),
    inventory: z.number(),
  }),
})
 
export const collections = { products }

Dane pokazują konkretną wartość biznesową: statyczna obudowa strony plus dynamiczne dane — cena, stan magazynu — odświeżane na żądanie i przechodzące przez ten sam typowany system. To rozwiązanie zmniejsza dystans między Astro a Next.js w zastosowaniach e-commerce bez rezygnowania z architektonicznych atutów Astro.

Fonts API — zarządzanie krojami pisma w standardzie

Poprawne ładowanie fontów to pole minowe: preload, fonty zastępcze, hosting lokalny kontra Google Fonts, prywatność użytkowników, CLS wynikający z zamiany kroju. Astro 6 eliminuje to pole minowe jedną konfiguracją.

// astro.config.mjs
import { defineConfig, fontProviders } from 'astro/config'
 
export default defineConfig({
  fonts: [
    {
      provider: fontProviders.google(),
      name: 'Inter',
      cssVariable: '--font-inter',
      weights: ['400', '600', '700'],
      styles: ['normal'],
      subsets: ['latin', 'latin-ext'],
    },
  ],
})

Podczas budowania Astro pobierze wskazane kroje pisma, skopiuje je do lokalnych zasobów projektu, wygeneruje font-display: swap z dopasowanymi fontami zastępczymi i doda <link rel="preload"> dla najważniejszych wariantów. Produkcja nie odpytuje zewnętrznych serwerów Google Fonts, ręczna konfiguracja przestaje istnieć.

Dla serwisów obsługujących polskie znaki diakrytyczne — czyli dla większości rodzimych projektów — obsługa podzbioru latin-ext działa bez kompromisów w standardzie.

Content Security Policy — wbudowane wsparcie

Obsługa nagłówków CSP to najdłużej oczekiwana funkcja w historii Astro. Wdrażamy ją teraz jednym przełącznikiem. Zamiast wielodniowej konfiguracji haszy skryptów — deklaratywna konfiguracja w pliku projektu.

// astro.config.mjs
export default defineConfig({
  security: {
    csp: {
      algorithm: 'SHA-512',
      directives: [
        "default-src 'self'",
        "img-src 'self' https://images.cdn.example.com",
      ],
    },
  },
})

Astro generuje nagłówek CSP albo równoważny meta, razem z hashami dla wbudowanych skryptów i stylów — w tym ładowanych przez mechanizm wysp. Dla serwisów objętych audytami bezpieczeństwa to różnica między tygodniami pracy a jedną linią konfiguracji.

Nowy kompilator napisany w Rust

Astro 6 dostarcza eksperymentalny kompilator w Rust, docelowo zastępujący wariant oparty na Go. Na dużych projektach z tysiącami komponentów różnica w czasie budowania jest wyraźna. Na blogu z 80 artykułami MDX — znikoma. Kompilator jest opcjonalny i pozostaje w fazie beta, ale kierunek jest jasny: szybkość kompilacji staje się przewagą architektury.

Zmiany łamiące kompatybilność — na co zwrócić uwagę

Lista zmian łamiących kompatybilność jest długa, ale większość dotyczy przestarzałych API, które w zadbanych projektach i tak powinny być już usunięte. Oto najważniejsze punkty:

• Obowiązkowe środowisko Node 22+ — wsparcie dla Node 20 wygasa w kwietniu 2026 r., dlatego Astro 6 oficjalnie porzuca gałęzie 18 i 20. Upewnij się, że CI, Dockerfile i infrastruktura serwerowa używają właściwej wersji.
• Usunięto przestarzałe API: Astro.glob() (zastąpione przez import.meta.glob), emitESMImage(), komponent <ViewTransitions /> (jego rolę przejął <ClientRouter />) oraz stary system Content Collections.
• Zablokowano wsparcie dla pliku astro.config.cjs — obsługiwane są wyłącznie moduły ESM (astro.config.mjs lub wersja oparta na TypeScript .ts).
• Przesiadka na Vite 7 — koniecznie zweryfikuj kompatybilność, jeżeli Twój projekt korzysta z niestandardowych wtyczek Vite.
• Zmiana w wyliczaniu identyfikatorów dla nagłówków Markdown — bezpośrednie linki do wybranych sekcji w istniejących wpisach mogą wymagać przekierowań.
• Znaczne przebudowanie adaptera Cloudflare (v13) — firma rekomenduje od teraz usługę Workers dla całkiem nowych projektów. Serwisy postawione na Cloudflare Pages powinny zostać przeanalizowane pod kątem nowej ścieżki migracyjnej i tabeli zgodności.

Lista kontrolna przed migracją

Przed uruchomieniem komend aktualizujących wdrażamy krótką ocenę ryzyka. Problemy nigdy nie leżą w samym Astro 6 — leżą w adapterach, wtyczkach i bibliotekach dołączonych do projektu.

• Node 22.12.0 lub wyższy — lokalnie i w CI.

• Usunięte wywołania Astro.glob() — zastąpione import.meta.glob() lub Content Collections.

• Schematy Zod — import z z astro/zod, nie z astro:content.

• Własne wtyczki Vite — weryfikacja kompatybilności z Vite 7.

• Adapter Cloudflare — testowa wersja na Workers, weryfikacja bindingów, statycznych zasobów i sesji.

• Bezpośrednie linki do sekcji artykułów — nowy algorytm identyfikatorów nagłówków Markdown może je zepsuć.

Typowy blog z kilkudziesięcioma plikami MDX i przewidywalną architekturą da się zwykle przenieść w 2-4 roboczogodziny, ale większe projekty z własnymi integracjami wymagają kilku dni testów i poprawek.

Jak bezpiecznie zaktualizować istniejący projekt

Astro dostarcza narzędzie CLI, które automatyzuje aktualizację rdzenia i oficjalnych integracji.

npx @astrojs/upgrade

Narzędzie podnosi wersję astro, aktualizuje wspierane pakiety @astrojs/* i raportuje konflikty peer dependencies. Po aktualizacji weryfikuj projekt przez oficjalny przewodnik po migracji — szczególnie przy niestandardowych adapterach.

Proces migracji na poziomie produkcyjnym:

1. Nowa gałąź w systemie kontroli wersji — aktualizacja tylko na niej.
2. astro check — weryfikacja typowania, łatanie wykrytych błędów.
3. astro build ręcznie — ostrzeżenia wskazują, co nie pasuje nowemu kompilatorowi.
4. Test interaktywności w środowisku bliskim produkcji: workerd albo Node.
5. Deployment testowy — weryfikacja Core Web Vitals i brak nowych błędów indeksowania w Google Search Console.

Czy to odpowiedni czas na przesiadkę?

Astro 6 jest produkcyjnie stabilne od marca 2026, dlatego nowe projekty zaczynaj na Astro 6 i nie rób wyjątków od tej reguły.

Jeśli hosting opierasz na Cloudflare, największą korzyścią jest lokalne środowisko identyczne z produkcją. Przy innych dostawcach zyskujesz Fonts API, stabilne CSP, Live Content Collections i wygodniejszą pracę programistyczną.

Dla istniejących projektów na Astro 5 — migracja etapami jest możliwa, ale odkładanie jej w nieokreśloną przyszłość nie jest dobrym rozwiązaniem. Im bardziej rozjadą się wersje adapterów i integracji, tym droższa stanie się późniejsza aktualizacja.