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

Astro 6Astro 6 to główne wydanie frameworka Astro z marca 2026 r., z nowym serwerem programistycznym, obsługą Live Content Collections, Fonts API, CSP i wymaganiem Node w wersji 22.12+. to największa aktualizacja Astro od lat. Przejście z gałęzi 5.x na 6.x nie jest więc zwykłym podbiciem wersji w package.json. Zmienia się lokalny serwer programistyczny, pogłębia integracja z Cloudflare Workers, dochodzą stabilne Live Content Collections, wbudowane zarządzanie fontami i obsługa Content Security Policy.

W tym wpisie pokażę, co realnie zmieniło się z perspektywy programisty i o czym trzeba pamiętać przed migracją — patrząc oczami osoby, która utrzymuje kilka produkcyjnych witryn w Astro (między innymi StriveLab oraz inspektomat.pl).

Kontekst — Cloudflare i Astro razem

16 stycznia 2026 roku firma Cloudflare ogłosiła przejęcie The Astro Technology Company. Zespół rozwijający Astro dołączył do Cloudflare, ale framework pozostał na licencji MIT i zachował niezależność od platformy docelowej — nadal możesz go wdrażać na Netlify, Vercel, AWS czy własny serwer VPS. Z Astro 6 przyszła natomiast głęboka integracja z ekosystemem Cloudflare, która istotnie zmienia sposób lokalnej pracy z frameworkiem.

To przejęcie to jasny sygnał podziału 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ększą techniczną zmianą w Astro 6 jest przebudowa polecenia astro dev. Do tej pory lokalny serwer programistyczny działał w Node.js, podczas gdy produkcja często korzystała z zupełnie innego środowiska: Cloudflare Workers, Deno albo Bun. To tworzyło klasyczny problem „u mnie działa, na produkcji nie”, bo błędy ujawniały się dopiero po wdrożeniu.

Astro 6 wykorzystuje nowe Vite Environment API i potrafi uruchamiać kod lokalnie w dokładnie tym samym środowisku, w którym będzie działał na produkcji. Dla użytkowników infrastruktury Cloudflare oznacza to, że astro dev uruchamia się bezpośrednio w workerd (to ten sam silnik JavaScript, z którego korzysta Cloudflare Workers), oferując pełny dostęp do platformowych interfejsów API — Durable Objects, KV Namespaces, R2 Storage, Workers Analytics Engine czy bazy D1 — bez konieczności stosowania jakichkolwiek zaślepek ani symulacji.

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

W praktyce oznacza to mniej obejść wokół Astro.locals.runtime i mniej bibliotek udających usługi Cloudflare w lokalnym środowisku. Jeśli korzystasz z KV, R2 albo Durable Objects, możesz pracować na nich lokalnie z pełnym wsparciem natychmiastowego przeładowywania modułów (Hot Module Replacement).

Live Content Collections — dynamiczne treści bez przebudowywania projektu

Do niedawna mechanizm Content Collections bazował wyłącznie na etapie budowania projektu — cała zawartość była ładowana i weryfikowana w trakcie generowania statycznych plików. Takie rozwiązanie świetnie sprawdza się w przypadku blogów czy dokumentacji, ale kompletnie nie zdaje egzaminu dla danych podlegających zmianom w czasie rzeczywistym (stany magazynowe, aktualne ceny, unikalne dane użytkownika).

Astro 6 wprowadza Live Content Collections. To ten sam typowany system pracy z treścią, ale uzupełniony o loadery danych wykonywane na żądanie w czasie działania aplikacji. Schematy Zod i autouzupełnianie w edytorze zostają, tylko źródło danych może być odpytywane 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 }

To zmniejsza dystans między Astro a Next.js w prostszych zastosowaniach e-commerce. Dostajesz statyczną obudowę strony, ale wybrane dane, np. cena albo stan magazynu, mogą być odświeżane dynamicznie i nadal przechodzić przez ten sam typowany system.

Fonts API — zarządzanie krojami pisma w standardzie

Niemal każdy projekt webowy używa niestandardowych krojów pisma, a ich poprawne ładowanie łatwo zepsuć. Trzeba pamiętać o preloadzie, fontach zastępczych, hostowaniu plików u siebie albo przez Google Fonts oraz o prywatności użytkowników. Astro 6 dodaje wbudowane Fonts API, które porządkuje większość tej pracy.

// 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. W efekcie produkcja nie musi odpytywać zewnętrznych serwerów Google Fonts, a Ty nie rzeźbisz całej konfiguracji ręcznie.

Dla serwisów obsługujących polskie znaki diakrytyczne (czyli de facto dla większości rodzimych projektów) to spory atut — obsługa podzbioru latin-ext działa bez żadnego zająknięcia w standardzie.

Content Security Policy — wbudowane wsparcie

Obsługa nagłówków CSP to najprawdopodobniej najczęściej powtarzająca się prośba społeczności w całej historii rozwoju Astro. Wraz z wersją 6 mechanizm ten stał się stabilną i wbudowaną częścią frameworka. Zamiast manualnie zarządzać wartościami nagłówków i dbać o funkcje haszujące skrypty, wystarczy aktywować odpowiednią opcję w pliku konfiguracyjnym.

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

Astro samodzielnie wygeneruje nagłówek CSP albo równoważny znacznik meta, razem z hashami dla wbudowanych skryptów i stylów, także tych ładowanych przez mechanizm wysp. Dla serwisów objętych audytami bezpieczeństwa i korporacyjnymi wymaganiami to duża oszczędność pracy. Zamiast wielodniowej konfiguracji dostajesz jeden przewidywalny przełącznik.

Nowy kompilator napisany w Rust

Astro 6 dostarcza eksperymentalny wariant kompilatora napisanego w Rust, który docelowo ma zastąpić aktualną wersję opartą na Go. Na razie jest opcjonalny i pozostaje w fazie beta, ale już teraz potrafi być wyraźnie szybszy od poprzednika. Najwięcej zyskają duże projekty z tysiącami komponentów.

W moim przypadku, przy stronie z ponad 80 artykułami MDX, różnica w czasie budowania jest niewielka. Przy dużej dokumentacji open source z tysiącami podstron kompilator Rust może jednak urwać z buildów realne minuty.

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. 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 zrób krótką ocenę ryzyka. Problemy zwykle nie leżą w samym Astro 6, tylko w adapterach, wtyczkach i bibliotekach dołączonych do projektu.

• Upewnij się, że lokalnie i w CI działa Node co najmniej 22.12.0.
• Usuń wywołania Astro.glob(); zastąp je import.meta.glob() albo przenieś treści na Content Collections.
• Zweryfikuj schematy Zod — importuj obiekt z bezpośrednio z paczki astro/zod, a nie z dawnego astro:content.
• Jeżeli posiadasz własne wtyczki konfigurujące narzędzie Vite, upewnij się co do ich poprawności działania w Vite 7.
• Przy adapterze Cloudflare wystaw wersję testową na Workers i sprawdź bindingi, ładowanie plików statycznych oraz obsługę sesji.
• Skontroluj bezpośrednie linki do sekcji w starszych artykułach, bo zmiany w parsowaniu Markdown mogą zmienić identyfikatory nagłówków.

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

Jak bezpiecznie zaktualizować istniejący projekt

Twórcy Astro udostępniają narzędzie CLI, które automatyzuje aktualizację rdzenia i oficjalnych integracji.

npx @astrojs/upgrade

Narzędzie podnosi wersję astro, aktualizuje wspierane pakiety @astrojs/* i informuje o potencjalnych konfliktach zależności równorzędnych (peer dependencies). Po aktualizacji nadal przejdź przez oficjalny przewodnik po migracji i sprawdź go w kontekście własnej aplikacji, szczególnie jeśli używasz niestandardowych adapterów.

W praktyce trzymam się takiego procesu:

1. Stwórz nową gałąź w systemie kontroli wersji i wykonaj aktualizację właśnie na niej.
2. Zleć wykonanie weryfikacji programem astro check i załataj wyłapane nieścisłości w obrębie typowania.
3. Uruchom ręcznie astro build — ostrzeżenia pokażą, co jeszcze nie pasuje nowemu kompilatorowi.
4. Przetestuj interaktywność i lokalne działanie w środowisku możliwie bliskim produkcji: przez workerd albo Node.
5. Wdróż wersję testową, sprawdź Core Web Vitals i upewnij się w Google Search Console, że nie pojawiły się nowe błędy indeksowania.

Czy to odpowiedni czas na przesiadkę?

Astro 6 jest produkcyjnie użyteczne i stabilne od premiery w marcu 2026. Jeśli hosting opierasz na Cloudflare, największą korzyścią jest lokalne środowisko bliższe produkcji. Przy innych dostawcach nadal zyskujesz Fonts API, stabilne CSP, Live Content Collections i wygodniejszą pracę programistyczną.

Nowe projekty zaczynałbym już na Astro 6. Istniejące aplikacje na Astro 5 można migrować etapami, ale nie warto odkładać tego zbyt długo. Im bardziej rozjadą się wersje adapterów, integracji i automatyzacji testów, tym droższa będzie późniejsza aktualizacja.

Podsumowanie

Astro 6 wzmacnia kierunek, który framework miał od początku: szybkie strony treściowe, mało JavaScriptu w przeglądarce, typowane kolekcje i coraz lepsza zgodność między lokalnym developmentem a produkcją. Przejęcie przez Cloudflare daje projektowi stabilniejsze finansowanie, a licencja MIT nadal chroni przed zamknięciem ekosystemu i twardym uzależnieniem od jednego dostawcy.

Jeśli planujesz stronę internetową w Astro albo chcesz zmodernizować istniejący projekt bez ryzykowania SEO budowanego miesiącami, odezwij się przez formularz kontaktowy.