If you build an Astro 7 site with Server-Side Rendering (SSR) today, you deploy to Cloudflare Workers. As of @astrojs/cloudflare version 13, the adapter completely removed support for Cloudflare Pages. If your Astro project is fully static (SSG), you can still choose between Cloudflare Pages and the newer Cloudflare Workers Assets.

The choice dictates your configuration, caching limits, local testing capabilities, and your monthly bill.

The End of Pages for Astro SSR

Cloudflare acquired the Astro project in January 2026. Following the acquisition, the deployment ecosystem standardized around the native Workers runtime, known as workerd. The @astrojs/cloudflare adapter dropped Pages support entirely in version 13.

When you configure Astro with output: 'server' and add the Cloudflare adapter, the build process compiles your application into a Cloudflare Worker. The output splits into two components: a dist/client directory for static files like stylesheets and images, and a dist/_worker.js directory containing the application logic.

You cannot upload this output to Cloudflare Pages and expect dynamic routes or API endpoints to function. Pages no longer handles the Astro SSR entrypoint. Any server-rendered components, API endpoints, or server islands require the Cloudflare Workers environment.

Deploying Static Sites Without an Adapter

If you use the default static output (SSG), you do not need the @astrojs/cloudflare adapter. You compile your Markdown or MDX collections into static HTML and serve the resulting dist directory.

For static deployments, you have two native options:

  1. Cloudflare Pages via Git integration. You connect your repository in the Cloudflare dashboard, set the build command to npm run build, and specify dist as the output directory. The Pages service executes the build on its own infrastructure and serves the static files.
  2. Cloudflare Workers Assets. You deploy the static site as a Worker asset bundle using the Wrangler CLI.

Workers Assets is the modern deployment path. You configure it by adding a wrangler.jsonc file to your project root:

{ "name": "astro-static-homelab", "compatibility_date": "2026-11-13", "assets": { "directory": "./dist", "not_found_handling": "404-page" } }

The not_found_handling key tells Cloudflare to serve your custom 404.html page when a route goes unmatched, replicating standard web server behavior without extra routing rules.

You deploy the static bundle directly from your terminal or CI pipeline:

# Build the Astro static site locally or in CI npm run build # Deploy to Cloudflare Workers Assets npx wrangler deploy

This method bypasses the Cloudflare Pages build queue. Your CI runner manages the node modules and build steps, and Wrangler uploads the finished assets directly to the edge.

Deploying SSR Sites With Cloudflare Workers

Dynamic routes require the @astrojs/cloudflare adapter. You must use this adapter if you implement server islands, authenticate users against a database, or render pages on demand.

Install the adapter using the Astro CLI:

npx astro add cloudflare

Configure your astro.config.mjs for server output:

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

The adapter configures the Vite plugin to generate the correct Worker manifest during the build. You still maintain a wrangler.jsonc file to define environment variables, database connections, or key-value namespaces.

Because Astro 7 relies on Node.js built-ins for specific SSR functionality, you must enable the nodejs_compat flag in your configuration:

{ "name": "astro-ssr-homelab", "compatibility_date": "2026-11-13", "compatibility_flags": ["nodejs_compat"] }

The imageService: 'passthrough' option tells Astro to skip local image optimization. The default image processor, Sharp, requires native binaries and does not run in the Cloudflare Workers V8 environment. You must pre-optimize your assets before deployment or use Cloudflare's edge image optimization service.

Local Preview and the V8 Runtime

Testing an SSR site locally requires an accurate emulation of the edge environment. Standard Node.js servers behave differently than Cloudflare Workers.

The @astrojs/cloudflare adapter integrates directly with Miniflare. When you run astro build followed by astro preview, the preview server runs workerd locally. This setup catches V8 compatibility issues before deployment.

If your code imports a Node.js library that relies on file system access (fs) or child processes (child_process), the preview server will throw an error. The V8 isolate model strictly limits these APIs for security and performance reasons. Running astro preview ensures your dependencies are compatible with the edge limits.

Connecting D1 and KV Bindings

Deploying Astro to Cloudflare Workers gives you direct access to Cloudflare's data services. You configure bindings in your wrangler.jsonc file.

To connect a D1 SQL database and a KV namespace:

{ "name": "astro-database-app", "compatibility_date": "2026-11-13", "compatibility_flags": ["nodejs_compat"], "kv_namespaces": [ { "binding": "SESSIONS", "id": "your-kv-id-here" } ], "d1_databases": [ { "binding": "DB", "database_name": "homelab-db", "database_id": "your-d1-id-here" } ] }

In your server-rendered Astro components, you query the database directly through the provided environment context. This architecture keeps database queries at the edge, executing in milliseconds alongside your HTML generation.

Caching and Cost Trade-Offs

The choice between static and SSR outputs dictates your Cloudflare bill.

Cloudflare Workers uses a strict usage-based billing model. At the time of writing, the Workers Free plan allows 100,000 requests per day with a maximum of 10 milliseconds of CPU time per invocation. Exceeding this limit causes Cloudflare to drop incoming requests.

The Workers Paid plan costs $5 USD per month minimum. This base fee includes 10 million requests and 30 million CPU milliseconds per month. Additional requests cost $0.30 USD per million. Cloudflare does not charge for egress bandwidth on either plan.

If your Astro site uses SSR, every dynamic page load triggers a Worker execution. A high-traffic blog with server output will quickly exhaust the daily free tier limit, pushing you to the Paid plan.

If your site is fully static (SSG) and deployed to Cloudflare Pages or Workers Assets, requests for HTML, CSS, and images bypass the Worker CPU limit. Static assets are served directly from the edge cache. A static Astro site can serve millions of page views per month without leaving the free tier.

For homelab users hosting a public portfolio or documentation site, SSG is the cheapest and most resilient path. Reserve SSR for applications that require live database queries, form processing, or user sessions.

Environment Variables and Secrets

Node.js developers expect environment variables to reside in process.env. The Cloudflare Workers runtime does not use the global Node.js process object.

When you deploy an Astro SSR site to Workers, environment variables are passed through the request context. You configure secrets using Wrangler instead of a .env file for production:

npx wrangler secret put API_KEY

In your Astro components, you access these variables using the env object provided by the adapter runtime. Hardcoding process.env in your scripts will cause the Worker to crash in production.

What's Next

FAQ

Can I deploy Astro SSR to Cloudflare Pages?

No. Since Astro 6 and the @astrojs/cloudflare v13 adapter, Cloudflare Pages is no longer supported for Server-Side Rendering (SSR). You must use Cloudflare Workers.

How much does it cost to host Astro on Cloudflare Workers?

The Free tier includes 100,000 requests per day. The Paid plan starts at $5 per month and includes 10 million requests and 30 million CPU milliseconds.

Do I need the @astrojs/cloudflare adapter for a static site?

No. If you build a purely static Astro site (SSG), you do not need the adapter. You can serve the static output directly via Cloudflare Workers Assets or Pages.

Originally published at linuxcore.dev.