Back to Blog
Cloudflare-WorkersCloudflare-PagesAstroStatic-AssetsMigration-RunbookDevOps

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.

·4 min read·Fonda Digital Engineering

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.toml vs 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:

  1. Asset Caching Headers: Inspect network responses in DevTools to confirm static assets carry cf-cache-status: HIT with max-age=31536000, immutable.
  2. Trailing Slash Consistency: Test both /blog and /blog/ to ensure your html_handling rules redirect cleanly without 404 loops.
  3. 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.
  4. 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:

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?→
Historically, Cloudflare maintained separate platforms for Pages (Git-integrated static/functions hosting) and Workers (serverless compute). Workers Static Assets unifies both into a single runtime architecture, eliminating dual configuration files, unifying wrangler deployment workflows, and providing direct access to native Workers bindings (KV, D1, Queues, Vectorize).
What are the primary performance advantages of Workers Static Assets over legacy Pages?→
Workers Static Assets eliminates routing hops between Pages CDN and Worker functions, serves static assets directly from edge server memory caches with sub-10ms latency, and removes invocation billing costs for static asset requests.
How long does migrating an existing Astro project take?→
The migration requires approximately 15 minutes: updating the @astrojs/cloudflare adapter configuration, creating a unified wrangler.jsonc file with assets binding, and modifying the CI/CD deployment script from wrangler pages deploy to wrangler deploy.
Senior Engineering Advisory

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.

Book Technical Consultation →
START AN ENGINEERING ENGAGEMENT

Let's build.

Send over your technical brief or project scope. You'll receive an assessment directly from a senior technical lead within 4 business hours.

Fonda Digital

Senior full-stack engineering boutique based in Ljubljana and Izola, Slovenia. Direct access to the engineer writing your code, with zero junior hand-offs.

BASE:Ljubljana / Izola, Slovenia
RESPONSE WINDOW:Within 4 Business Hours (CET)
DIRECT CHANNEL:[email protected]
CURRENT TIME: LJUBLJANA--:--:-- CET
Estimated Budget

Automated spam protection.