Astro 6 i przewodnik po nowościach w tym Cloudflare Workers

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

Astro 6 i Cloudflare: dlaczego ta integracja jest ważna?

16 stycznia 2026 roku Cloudflare przejął The Astro Technology Company. Framework pozostał na licencji MIT i nadal działa niezależnie od platformy, na przykład na Netlify, Vercel, AWS i własnym VPS-ie. 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?.

Workerd jako nowe środowisko uruchomieniowe w Astro 6

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 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, czyli w 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 i masz pełne HMR.

Live Content Collections w Astro 6 bez przebudowywania projektu

Klasyczny mechanizm Content Collections bazował wyłącznie na etapie budowania, więc cała zawartość była ł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, takich jak stany magazynowe, aktualne ceny i spersonalizowane dane użytkownika, był to mur techniczny.

Astro 6 burzy ten mur, wprowadzając Live Content Collections. To 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ą, a zmienia się tylko źródło danych, które jest 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 }

Dane pokazują konkretną wartość biznesową: statyczna obudowa strony plus dynamiczne dane, takie jak cena i 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 w Astro 6 i zarządzanie krojami pisma

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 w Astro 6

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 dostajesz deklaratywną konfigurację 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 Astro napisany w Rust

Astro 6 dostarcza eksperymentalny kompilator w Rust, który docelowo zastąpi 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 będzie raczej znikoma. Kompilator jest opcjonalny i pozostaje w fazie beta, ale kierunek jest jasny: szybkość kompilacji staje się przewagą architektury.

Zmiany łamiące kompatybilność w Astro 6

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+ ponieważ 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ępuje import.meta.glob, znikają też emitESMImage(), komponent ViewTransitions, którego rolę przejął ClientRouter, oraz stary system Content Collections.

• Zablokowano wsparcie dla pliku astro.config.cjs. Obsługiwane są wyłącznie moduły ESM, czyli astro.config.mjs albo wersja oparta na TypeScript .ts.

• Przesiadka na Vite 7 wymaga weryfikacji kompatybilności, jeżeli Twój projekt korzysta z niestandardowych wtyczek Vite.

• Zmiana w wyliczaniu identyfikatorów dla nagłówków Markdown oznacza, że bezpośrednie linki do wybranych sekcji w istniejących wpisach mogą wymagać przekierowań.

• Znaczne przebudowanie adaptera Cloudflare (v13) sprawia, że firma rekomenduje 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ą do Astro 6

Przed uruchomieniem komend aktualizujących wdrażamy krótką ocenę ryzyka. Problemy nigdy nie leżą w samym Astro 6, tylko 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 z importem z z astro/zod, a nie z astro:content.

• Własne wtyczki Vite po weryfikacji kompatybilności z Vite 7.

• Adapter Cloudflare po testach na Workers, z weryfikacją bindingów, statycznych zasobów i sesji.

• Bezpośrednie linki do sekcji artykułów, ponieważ 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ć projekt do Astro 6?

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 i aktualizacja tylko na niej.
2. astro check w celu weryfikacji typowania i naprawy wykrytych błędów.
3. astro build uruchomione ręcznie, aby ostrzeżenia pokazały, co nie pasuje nowemu kompilatorowi.
4. Test interaktywności w środowisku bliskim produkcji: workerd albo Node.
5. Deployment testowy oraz weryfikacja Core Web Vitals i braku nowych błędów indeksowania w Google Search Console.

Czy warto migrować do Astro 6 teraz?

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.