Migrating Astro from Cloudflare Pages to Workers Static Assets: 15-Minute Runbook
The 15-minute migration runbook: moving Astro applications from Cloudflare Pages to Cloudflare Workers Static Assets with unified wrangler.jsonc architecture.
In 2024 and 2025, deploying full-stack Astro applications to Cloudflare typically meant choosing Cloudflare Pages: an exceptional Git-backed hosting platform that automatically built static assets and deployed serverless functions via the @astrojs/cloudflare adapter.
However, developers frequently struggled with the artificial architectural divide between Cloudflare Pages and Cloudflare Workers:
- Separate dashboards and project management interfaces.
- Confusing differences in binding configurations (
wrangler.tomlvs dashboard environment variables). - Limitations when binding advanced Cloudflare primitives like Queues, Vectorize, and Hyperdrive.
In 2026, Cloudflare unified its edge compute ecosystem with Cloudflare Workers Static Assets.
Workers now natively support static asset hosting alongside serverless compute in a single unified architecture. Static files are served directly from Cloudflare’s global edge network at zero execution cost, while dynamic SSR routes execute in the same unified Worker script.
Below is our 15-minute migration runbook: detailing how to upgrade your Astro project from Cloudflare Pages to Cloudflare Workers Static Assets.
1. Migration Step 1: Updating @astrojs/cloudflare Adapter
Ensure your project uses the modern Astro Cloudflare adapter and Wrangler CLI supporting native Workers Static Assets:
npm install @astrojs/cloudflare@latest wrangler@latest --save-dev
In your astro.config.mjs, ensure your adapter is configured for edge output:
// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
import tailwind from '@astrojs/tailwind';
export default defineConfig({
output: 'static', // or 'server' for hybrid SSR
adapter: cloudflare({
imageService: 'cloudflare',
platformProxy: {
enabled: true,
},
}),
integrations: [tailwind()],
});
2. Migration Step 2: Creating the Unified wrangler.jsonc
Legacy Pages relied on custom dashboard settings or a limited wrangler.toml. In the unified Workers architecture, all environment configuration, static asset routing, and KV/D1 database bindings live in a single, version-controlled wrangler.jsonc file:
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "fonda-digital-web",
"main": "./dist/_worker.js/index.js",
"compatibility_date": "2026-10-01",
"compatibility_flags": ["nodejs_compat"],
// Static assets configuration
"assets": {
"directory": "./dist",
"binding": "ASSETS",
"html_handling": "auto-trailing-slash",
"not_found_handling": "single-page-application"
},
// Edge KV bindings (e.g. for caching or rate limiting)
"kv_namespaces": [
{
"binding": "CACHE_KV",
"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
],
"observability": {
"enabled": true
}
}
The key directive is "assets": { "directory": "./dist" }. This instructs Cloudflare’s deployment engine to upload the static HTML, CSS, JS, and image assets to the edge storage network, routing incoming requests directly to the fastest local edge node.
3. Migration Step 3: Updating CI/CD Deployment Commands
In your GitHub Actions workflow or deployment scripts, replace the legacy wrangler pages deploy command with the standard wrangler deploy:
# ❌ Legacy Cloudflare Pages Deployment
- name: Deploy to Cloudflare Pages
run: npx wrangler pages deploy dist --project-name=fonda-web
# ✅ Modern Cloudflare Workers Static Assets Deployment
- name: Deploy to Cloudflare Workers
run: npx wrangler deploy
wrangler deploy reads your wrangler.jsonc, automatically builds the asset manifest, uploads static files with delta content hashing, and deploys any worker function code in a single atomic transaction taking under 10 seconds.
4. Key Differences: Pages vs. Workers Static Assets
To understand what changes after migration, review this operational comparison:
| Architectural Feature | Legacy Cloudflare Pages | Modern Workers Static Assets (2026) |
|---|---|---|
| Deployment Command | wrangler pages deploy |
Unified wrangler deploy |
| Config Schema | Split between UI & wrangler.toml |
Single wrangler.jsonc |
| Static Request Cost | 0 requests billed | 0 requests billed (Free edge asset cache) |
| Edge Function Latency | Inter-service hop between CDN and Worker | 0ms internal hop (Single process execution) |
| Binding Capabilities | Limited native bindings | Full access to D1, KV, Vectorize, Hyperdrive, Queues |
| Observability | Basic request analytics | Full Workers Tracing & Tail logs integration |
5. Post-Migration Verification Checklist
After deploying your updated worker, verify these four operational checkpoints:
- Asset Caching Headers: Inspect network responses in DevTools to confirm static assets carry
cf-cache-status: HITwithmax-age=31536000, immutable. - Trailing Slash Consistency: Test both
/blogand/blog/to ensure yourhtml_handlingrules redirect cleanly without 404 loops. - Dynamic API Functions: If your Astro site utilizes SSR endpoints (e.g.
/api/contact), submit a test payload to verify environment variables and secret bindings resolve properly. - Custom Error Pages: Test a non-existent URL (e.g.
/non-existent-page) to confirm your custom 404 page renders rather than Cloudflare’s default error banner.
6. Summary: Clean, Modern Edge Architecture
Migrating from Cloudflare Pages to Workers Static Assets is one of the highest-leverage 15-minute upgrades an Astro engineering team can perform in 2026.
By unifying your configuration under wrangler.jsonc:
- You eliminate the clunky dual-dashboard workflows of legacy Pages.
- You unlock instant, zero-cost static edge delivery backed by Cloudflare’s global anycast network.
- You gain native, friction-free bindings to high-performance edge databases (D1, KV, Vectorize).
Your web infrastructure becomes simpler, faster, and permanently future-proofed.
To explore related edge deployment guides and modern web architectures:
- Study our comprehensive guide Astro 6/7 on Cloudflare workerd Edge Architecture.
- Review CI/CD preview automation in Automated PR Preview Environments with GitHub Actions.
- Learn core headless architecture in The Architecture of Headless Web Performance: Astro vs Next.js.
Need assistance migrating enterprise web properties to Cloudflare Workers Static Assets? Contact our edge engineering squad to schedule a deployment audit.
Frequently Asked Questions
Why did Cloudflare consolidate Pages into Workers Static Assets in 2026?→
What are the primary performance advantages of Workers Static Assets over legacy Pages?→
How long does migrating an existing Astro project take?→
Need senior engineering firepower on your next release?
Direct access to senior engineers specializing in ultra-fast Astro, Next.js, and high-converting architectures. No account managers, 4-hour SLA.