
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"
}
}
namebecomes the Worker's name and the first part of its test URL.compatibility_dateshould be the date you first deploy.assets.directoryis the folder Astro builds into.not_found_handling: "404-page"tells Cloudflare to answer unknown URLs with your404.htmland a 404 status. Without it, your customsrc/pages/404.astropage 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
| Limit | Free plan | Paid plan |
|---|---|---|
| Files per deployment | 20,000 | 100,000 |
| Size of one file | 25 MiB | 25 MiB |
Redirect rules in _redirects | 2,000 static, 100 dynamic | 2,000 static, 100 dynamic |
Rules in _headers | 100 | 100 |
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.
