Astro i Cloudflare Workers — deployment, bindings i lokalne środowisko developerskie

Cloudflare WorkersCloudflare Workers to edge runtime Cloudflare, w którym kod działa blisko użytkownika i ma dostęp do usług platformy przez bindings. w Astro 6 dostał bardzo mocną integrację: workerdworkerd to open-source'owy runtime Cloudflare, na którym działają Workery — ten sam lokalnie i na produkcji. Dzięki temu kod uruchamiany przez Wranglera zachowuje się tak jak po wdrożeniu. lokalnie, bindingsBindings to deklaratywne połączenia Workera z usługami Cloudflare (KV, R2, D1, Durable Objects), wstrzykiwane do kodu jako obiekty środowiska. do KV/R2/D1 bez mocków i HMR działający w środowisku edge. To nie jest demo z dokumentacji. To setup, na którym można oprzeć zwykłą stronę produkcyjną.

Dlaczego Cloudflare Workers, a nie Pages

Jasna odpowiedź: Cloudflare adapter v13 dla Astro 6 domyślnie celuje w Workers. Cloudflare rekomenduje Workers dla nowych projektów — Pages wymagają dodatkowej konfiguracji albo migracji.

Istniejący projekt na Pages? Migracja jest przewidywalna — Cloudflare przygotował oficjalny przewodnik migracyjny, a większość konfiguracji przenosi się 1:1.

Instalacja adaptera

Standardowa ścieżka:

npx astro add cloudflare

To instaluje @astrojs/cloudflare v13, dodaje do astro.config.mjs odpowiednią konfigurację i tworzy szkielet wrangler.jsonc.

Po instalacji Twój astro.config.mjs wygląda mniej więcej tak:

import { defineConfig } from 'astro/config'
import cloudflare from '@astrojs/cloudflare'
 
export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    imageService: 'cloudflare',
  }),
})

Dwie rzeczy warte uwagi:

• output: 'server' — cały Astro renderuje się on-demand na edge. Alternatywnie klasyczne 'static' (w tym wypadku adapter nie jest potrzebny). Tryb 'hybrid' nie istnieje od Astro 5.0 — został scalony ze 'static': domyślnie strony są prerenderowane, a pojedyncze trasy oznaczasz export const prerender = false, by renderować je on-demand.
• imageService: 'cloudflare' — optymalizacja obrazów przez Cloudflare Image Resizing. Alternatywnie 'compile' dla build-time optimization na trasach prerenderowanych albo domyślna konfiguracja adaptera, jeśli nie potrzebujesz edge'owej transformacji obrazów.

Lokalny dev — workerd zamiast Node

To największa zmiana Astro 6 dla użytkowników Cloudflare. Wcześniej astro dev działał w Node.js, a produkcja w workerd. Teraz lokalny dev działa w identycznym workerd co produkcja — klasyczny błąd „działa lokalnie, nie działa na prodzie" przestaje istnieć.

npm run dev

Pod spodem Astro:

1. Bootstrapuje Vite z Cloudflare Vite plugin.
2. Uruchamia workerd jako runtime dla Twojego kodu.
3. Zapewnia dostęp do platform API (KV, R2, D1, Durable Objects) — lokalnie, bez mockowania.

Skutek jest prosty: kod z cloudflare:workers API działa tak samo w dev i na produkcji. Astro.locals.runtime workaround znika, obejścia przestają być potrzebne, a importy z cloudflare:* działają bezpośrednio w astro dev.

Bindings — KV, R2, D1, Durable Objects

Bindings to sposób, w jaki Worker (i Twoje Astro) łączy się z zasobami Cloudflare: KVKV, czyli Workers KV, to rozproszony magazyn klucz-wartość Cloudflare, zoptymalizowany pod szybki odczyt na edge. (Key-Value store), R2R2 to obiektowy magazyn plików Cloudflare zgodny z API Amazona S3, bez opłat za transfer wychodzący. (storage zgodny z S3), D1D1 to serverlessowa baza SQL Cloudflare oparta na SQLite, replikowana na edge i dostępna w Workerach przez binding. Rozliczana za odczyty/zapisy, skaluje się do zera. (SQLite), Durable ObjectsDurable Objects to prymityw Cloudflare do współbieżnego, trwałego stanu — pojedyncza instancja koordynująca dostęp do danych. (stateful compute).

Konfigurujesz je w wrangler.jsonc:

{
  "name": "moja-astro-strona",
  "main": "./dist/_worker.js/index.js",
  "compatibility_date": "2026-04-01",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
  },
  "kv_namespaces": [
    {
      "binding": "SESSIONS",
      "id": "xxx",
    },
  ],
  "r2_buckets": [
    {
      "binding": "MEDIA",
      "bucket_name": "strivelab-media",
    },
  ],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "strivelab-production",
      "database_id": "yyy",
    },
  ],
}

A w kodzie Astro korzystasz z nich przez context.locals.runtime.env:

---
// src/pages/api/get-session.ts
export const GET: APIRoute = async ({ request, locals }) => {
  const { env } = locals.runtime;
 
  const sessionId = request.headers.get('X-Session-Id');
  const session = await env.SESSIONS.get(sessionId, 'json');
 
  if (!session) {
    return new Response(null, { status: 404 });
  }
 
  return new Response(JSON.stringify(session), {
    headers: { 'Content-Type': 'application/json' },
  });
};
---

TypeScript wie o Twoich bindings — po uruchomieniu wrangler types w worker-configuration.d.ts pojawiają się typy, które Astro używa do typowania locals.runtime.env.

Typowanie bindings

W src/env.d.ts (lub worker-configuration.d.ts) deklarujesz typy:

/// <reference types="astro/client" />
 
type Runtime = import('@astrojs/cloudflare').Runtime<{
  SESSIONS: KVNamespace
  MEDIA: R2Bucket
  DB: D1Database
  API_KEY: string
}>
 
declare namespace App {
  interface Locals extends Runtime {}
}

Teraz wewnątrz każdej strony/API route locals.runtime.env.DB.prepare(...) ma pełne autocomplete i TypeScript rzuca błędy, jeśli próbujesz użyć niezadeklarowanego binding.

Deployment

Deploy robisz przez Wrangler:

npm run build
npx wrangler deploy

Albo połączenie w jednej komendzie w package.json:

{
  "scripts": {
    "deploy": "astro build && wrangler deploy"
  }
}

Wrangler wrzuca build (statyczne assets + Worker) na Cloudflare. Pierwsza deployment tworzy Worker pod {name}.{twoja-subdomena}.workers.dev. Potem dodajesz custom domain przez Cloudflare dashboard.

Środowiska — preview, staging, production

Astro 6 zmienił sposób obsługi środowisk. W Astro 5 budowałeś raz i deployowałeś z flagą --env. W Astro 6 build musi być oddzielny dla każdego środowiska, bo pre-rendering używa innych wartości zmiennych.

# Production
CLOUDFLARE_ENV=production astro build
wrangler deploy
 
# Staging
CLOUDFLARE_ENV=staging astro build
wrangler deploy --env staging

W wrangler.jsonc:

{
  "name": "moja-strona",
  "env": {
    "staging": {
      "name": "moja-strona-staging",
      "vars": {
        "API_URL": "https://api-staging.example.com",
      },
    },
    "production": {
      "name": "moja-strona",
      "vars": {
        "API_URL": "https://api.example.com",
      },
    },
  },
}

Dla większości projektów rekomenduję osobny workflow w CI/CD dla każdego środowiska — GitHub Actions z osobnym job dla staging i production, wyzwalany z innego brancha.

Static output vs server output

Najczęstszy błąd przy wdrożeniach Astro na Cloudflare to dodanie adaptera bez decyzji, czy projekt naprawdę potrzebuje runtime Workera.

Obrazy na Cloudflare Images

Astro 6 z adapterem Cloudflare v13 może używać Cloudflare Image Resizing do optymalizacji obrazów. Zamiast build-time'owej optymalizacji w Node (sharp), obrazy są transformowane na edge w runtime, jeśli ustawisz imageService: 'cloudflare'.

---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';
---
 
<Image src={heroImage} alt="Hero" width={1200} height={630} format="webp" />

Wynik: obraz automatycznie resize'owany, kompresowany, serwowany w formacie WebP/AVIF przez najbliższy edge. Żadnego build timu, żadnego konfigurowania sharp'a.

Jeśli wolisz klasyczny build-time optimization (np. masz już pipeline zdjęć w pamięci), ustaw imageService: 'compile' w konfiguracji adaptera.

Debugging produkcyjny — Workers Observability

Cloudflare Workers Dashboard daje Ci wgląd w logi, metryki, error rate. Dla dev experience rekomenduję również:

# Tail logów produkcyjnych w terminalu
wrangler tail

To streamuje logi w czasie rzeczywistym ze wszystkich instancji Workera. Przydatne szczególnie do debugowania problemów, które nie pojawiają się lokalnie.

Dla bardziej zaawansowanego monitoringu rozważ Cloudflare Workers Analytics Engine (do custom metrics) albo integrację z Sentry przez @sentry/cloudflare.

Zmienne środowiskowe i sekrety

Dwie kategorie:

Vars — plain-text, dostępne w kodzie, commitowane w wrangler.jsonc:

{
  "vars": {
    "PUBLIC_SITE_URL": "https://strivelab.pl",
    "DEFAULT_LOCALE": "pl",
  },
}

Secrets — ustawiane przez Wrangler CLI, zaszyfrowane na Cloudflare, nie są w kodzie:

wrangler secret put DATABASE_URL
# wrangler zapyta o wartość interaktywnie

Dla lokalnego dev tworzysz .dev.vars:

# .dev.vars (gitignore'owany)
DATABASE_URL=postgres://localhost:5432/dev
API_KEY=secret-key

W kodzie dostęp przez locals.runtime.env.DATABASE_URL.

Ograniczenia Workers — co musisz wiedzieć

Workers nie są Node.js, i ta różnica ma znaczenie przed zaprojektowaniem architektury, nie po deployu. Limit CPU time: free plan daje 10 ms na request, paid — domyślnie 30 s, konfigurowalne do 5 minut. CPU time to nie wall clock, więc fetch() do zewnętrznego API nie liczy się w limicie, ale ciężkie obliczenia — JSON processing, kryptografia, manipulacja obrazami — mogą trafić w ścianę. Bundle size nie może przekroczyć 3 MB skompresowanych na Free i 10 MB na Paid — dla typowego projektu Astro to nie problem, ale uważaj na moment.js, lodash bez tree-shakingu i pełne AWS SDK. Workers nie mają fs: statyczne zasoby są serwowane przez Assets binding, nie przez czytanie plików w runtime. Subrequest limit na Free to 50 fetch'y na invocation, na Paid — 10 000. Dla stron z wieloma wywołaniami API weryfikuj ten limit przed wdrożeniem, nie po.

Kiedy Cloudflare wygrywa, kiedy Vercel

W 2026 roku to realny podział rynku. Dane z projektów wskazują jasno:

Cloudflare + Astro wygrywa przy globalnym ruchu, niskim budżecie i storage blisko kodu: KV, R2, D1. Vercel zostaje lepszym wyborem przy Next.js, React Server Components, PPR i zespole, który ma już dobrze ułożony workflow. Nie przenosiłbym takiego projektu na siłę.

Dla stron Astro — domyślny wybór to Cloudflare. Dla aplikacji Next.js — Vercel. Szersze porównanie frameworków opisałem w osobnym artykule.