---
title: "How to Deploy an Astro Site to Cloudflare Workers"
description: "Deploy an Astro site to Cloudflare Workers static assets with Wrangler: config file, custom domain, CI on every push, and the limits to know."
url: https://seahawkmedia.com/development/deploy-astro-to-cloudflare-workers/
language: en
---

[Home](https://seahawkmedia.com/) / [Development](https://seahawkmedia.com/development/) /How to Deploy an Astro Site to Cloudflare Workers

Guide

# How to Deploy an Astro Site to Cloudflare Workers

![Ryan James](https://seahawkmedia.com/team/ryan-james.webp) By [Ryan James](https://seahawkmedia.com/author/ryan/) Reviewed by the [Seahawk editorial team](https://seahawkmedia.com/editorial-standards/) Updated November 15, 2026

Published November 15, 2026 6 min read

[Astro](https://seahawkmedia.com/astro/) [For businesses](https://seahawkmedia.com/small-business/)

**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:

```bash
npm install wrangler@latest --save-dev
```

## Step 2: Add a Wrangler config file

Create `wrangler.jsonc` in the project root:

```json
{
  "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

```bash
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:

```bash
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  35  | 2,000 static, 100 dynamic | 2,000 static, 100 dynamic |
| Rules in  36  | 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](https://developers.cloudflare.com/workers/platform/limits/).

## 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:

```bash
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](https://docs.astro.build/en/guides/deploy/cloudflare/) and [Cloudflare's Astro guide](https://developers.cloudflare.com/workers/framework-guides/web-apps/astro/) 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](https://seahawkmedia.com/guides/enterprise/choose-enterprise-wordpress-hosting/) explains the wider platform, the [Astro web hosts](https://seahawkmedia.com/best/astro-emdash-hosting/) list compares alternatives, and the [stack page](https://seahawkmedia.com/stack/) shows how Astro, EmDash and WordPress fit together on it. For more hosting how-tos, see our [hosting articles](https://seahawkmedia.com/hosting/).

## 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.

WP Services

## WordPress services at revolutionary pricing.

Productized WordPress services, from builds to care, delivered by Seahawk and tracked in one app. For the WordPress lovers.

[Go to WP Services](https://wpservices.com/) [Free homepage rebuild](https://seahawkmedia.com/free-homepage-rebuild/)

More in Development

[How to Host a Node.js App: Four Realistic Options and How to Choose November 15, 2026 · 6 min read](https://seahawkmedia.com/development/host-a-nodejs-app/) [How to Install EmDash and Get Your First Site Running November 15, 2026 · 6 min read](https://seahawkmedia.com/development/install-emdash/) [Astro Integrations: What They Are, How to Add One and Which to Add First November 15, 2026 · 6 min read](https://seahawkmedia.com/development/astro-integrations/)
