How to Deploy an Astro Site to Cloudflare Workers

By Seahawk November 15, 2026 6 min read

To deploy an Astro site to Cloudflare Workers, build it, add a short wrangler.jsonc that points at the dist folder, and run npx wrangler deploy. A pre-rendered Astro site needs no adapter and no Worker code: Cloudflare uploads the files as static assets and serves them from its network. seahawkmedia.com itself is an Astro site served from Workers static assets, and the steps below are the ones we use, including the CI job that deploys on every push.

What you need

  • An Astro project that builds locally with npx astro build.
  • A Cloudflare account. The free plan covers sites of up to 20,000 files.
  • Node.js 22.23.4 or later, which current Astro 7 releases require.

Cloudflare also has an older product, Pages. Cloudflare recommends Workers for new projects, so this guide uses Workers throughout.

Step 1: Install Wrangler

Wrangler is Cloudflare's command-line tool. Add it to the project as a development dependency so that everyone, including your CI job, uses the same version:

npm install wrangler@latest --save-dev

Step 2: Add a Wrangler config file

Create wrangler.jsonc in the project root:

{
  "name": "my-astro-site",
  "compatibility_date": "2026-11-15",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}
  • name becomes the Worker's name and the first part of its test URL.
  • compatibility_date should be the date you first deploy.
  • assets.directory is the folder Astro builds into.
  • not_found_handling: "404-page" tells Cloudflare to answer unknown URLs with your 404.html and a 404 status. Without it, your custom src/pages/404.astro page is not used.

There is no main entry because a static site has no Worker script to run.

Step 3: Preview the build locally

npx astro build && npx wrangler dev

wrangler dev serves the dist folder the way Cloudflare will, so you can check trailing slashes, the 404 page and redirects before anything is public.

Step 4: Deploy

Sign in once, then build and deploy:

npx wrangler login
npx astro build && npx wrangler deploy

Wrangler uploads the files and prints a URL in the form my-astro-site.your-subdomain.workers.dev. Later deploys skip files that have not changed.

Cloudflare treats the workers.dev address as a testing address and recommends a route or custom domain for production. It is also public, so keep it out of search results. Create public/_headers with this rule, which applies only to workers.dev hosts:

https://:version.:subdomain.workers.dev/*
  X-Robots-Tag: noindex

Step 5: Connect your domain

The domain must be an active zone in the same Cloudflare account. Add a route to wrangler.jsonc and deploy again:

"routes": [
  { "pattern": "www.example.com", "custom_domain": true }
]

Cloudflare creates the DNS record and issues the certificate for you. One catch: a custom domain cannot be created on a hostname that already has a CNAME record, so delete the old record first. You can do the same thing in the dashboard under the Worker's Settings, then Domains & Routes.

Step 6: Deploy on every push

You have two options. The simplest is Workers Builds, Cloudflare's own Git integration. In the dashboard, go to Workers & Pages, select Create application, import the repository and set:

  • Build command: npx astro build
  • Deploy command: npx wrangler deploy

The Worker name in the dashboard must match the name in wrangler.jsonc, or the build fails.

The second option is your own CI, which is what we use because our build has extra steps. Create an API token in Cloudflare from the Edit Cloudflare Workers template, then save it and your account ID as GitHub repository secrets named CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. This workflow is a trimmed copy of ours:

# .github/workflows/publish.yml
name: publish
on:
  push:
    branches: [main]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24, cache: npm }
      - run: npm ci
      - run: npm run build
      - name: Deploy to Cloudflare Workers
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        run: npx wrangler deploy

Wrangler reads both values from the environment, so there is no login step. Never commit the token to the repository.

Limits to know before you launch

LimitFree planPaid plan
Files per deployment20,000100,000
Size of one file25 MiB25 MiB
Redirect rules in _redirects2,000 static, 100 dynamic2,000 static, 100 dynamic
Rules in _headers100100

Requests for static assets are free and unlimited on both plans. The file count is the limit that large sites meet first: every page, image and script in dist counts. Our own build is well past 20,000 files, which is why this site runs on the paid plan. The current numbers are on Cloudflare's limits page.

Redirects, headers and trailing slashes

Redirects. Put a plain text file named _redirects in Astro's public/ folder, one rule per line. The default status is 302, so write 301 for permanent moves:

/old-page/ /new-page/ 301
/blog/* /articles/:splat 301

Headers. A _headers file in the same folder sets response headers by path. By default Cloudflare serves assets with Cache-Control: public, max-age=0, must-revalidate, so browsers always check for a fresh copy.

Trailing slashes. With the default setting, /about/ serves about/index.html and /about redirects to it. Astro builds pages in that folder format by default, so the two agree. If you set trailingSlash in Astro, keep it consistent with the html_handling option in Wrangler. We use trailingSlash: 'always' in Astro with "html_handling": "auto-trailing-slash".

When you need server code as well

If some pages must render on demand, add Astro's Cloudflare adapter. It installs the package, updates astro.config.mjs and creates the Wrangler config:

npx astro add cloudflare

You can also keep a static site and run a small Worker of your own in front of selected paths. Add main and an assets binding to the config, then list the paths in run_worker_first:

"main": "./worker/index.js",
"assets": {
  "directory": "./dist",
  "binding": "ASSETS",
  "run_worker_first": ["/api/*"]
}

Every other request is still answered from static assets without running code. We use this pattern for redirects that are too numerous for a rules file and for a media fallback. Two things to remember: rules in _redirects and _headers are not applied to responses your Worker generates, and Worker invocations count toward the free plan's 100,000 requests a day, while static asset requests do not.

Both the Astro deployment guide and Cloudflare's Astro guide cover the on-demand setup in more depth.

Is Workers the right host for your Astro site?

It suits content sites that want global delivery with no servers to patch, and teams that already keep DNS on Cloudflare. It is less convenient if your domain's DNS has to stay elsewhere, since custom domains need the zone on Cloudflare. Our guide to what Cloudflare does explains the wider platform, the Astro web hosts list compares alternatives, and the stack page shows how Astro, EmDash and WordPress fit together on it. For more hosting how-tos, see our hosting articles.

Frequently asked questions

Do I need the @astrojs/cloudflare adapter to deploy to Workers?

Not for a pre-rendered site. A static Astro build only needs a Wrangler config with assets.directory set to ./dist. Add the adapter when pages have to render on demand.

Is hosting an Astro site on Cloudflare Workers free?

For many sites, yes. Requests for static assets are free and unlimited, and the free plan allows 20,000 files per deployment. Larger sites need the paid plan for its 100,000-file limit.

Should I use Cloudflare Pages or Workers for Astro?

Use Workers for a new project. Cloudflare recommends Workers for new projects and publishes a migration guide for existing Pages sites.

Why does my custom 404 page not show?

Workers needs "not_found_handling": "404-page" inside the assets block of your Wrangler config. Without it, unknown URLs do not use the 404.html that Astro builds.

Why are my _redirects rules ignored?

Check three things: the file is in public/ so it lands in dist, you are within the limit of 2,000 static and 100 dynamic rules, and the path is not handled by Worker code. Redirect rules do not apply to responses a Worker generates.

Em Workers

EmDash and Astro sites at revolutionary pricing.

Lightning-fast, secure websites delivered on EmDash and Astro. For the AI-curious bunch.