How to Deploy an Astro Site to Cloudflare Workers

Cloudflare Workers is where this site lives, so these are the exact steps we used. You’ll need a free Cloudflare account and a finished Astro site.

Step 1: Install Wrangler

Wrangler is Cloudflare’s command-line tool. Add it to your project:

npm install wrangler@latest --save-dev

Step 2: Create a config file

Create a file called wrangler.jsonc in your project folder, next to package.json:

{
  "name": "my-site",
  "compatibility_date": "2026-11-06",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

Change name to your site’s name. It becomes part of your address. Set compatibility_date to today’s date.

The not_found_handling line tells Cloudflare to show your 404.astro page for missing addresses. Without it, visitors see a plain error.

Step 3: Build and deploy

Run these two commands:

npx astro build
npx wrangler deploy

The first time, Wrangler opens your browser so you can log in to Cloudflare. After that, it uploads your dist folder and prints your new address, which ends in workers.dev.

Open it. Your site is online.

Step 4: Make updates

Every time you change your site, run the same two commands again. To save typing, add a script to package.json:

"scripts": {
  "deploy": "astro build && wrangler deploy"
}

Now npm run deploy does both.

Deploy automatically from GitHub

If your project is on GitHub, Cloudflare can build and deploy it for you on every push. In the Cloudflare dashboard, go to Compute, then Workers & Pages, create an application, and import your repository. Set the build command to npx astro build and the deploy command to npx wrangler deploy.

We haven’t set this up for AstroBeginner yet, so those steps come from Cloudflare’s guide in the Astro docs.

Common problems

• “not logged in”: run npx wrangler login.
• A blank page or missing styles: make sure you ran astro build before wrangler deploy, and that directory points to ./dist.
• Old content after deploying: refresh with the cache cleared, or wait a minute.

Prefer a different host? Compare them in the best hosting for Astro, or use GitHub Pages instead.

Frequently asked questions

Is Cloudflare Workers free for a static site?

Cloudflare's documentation says requests for static files are free and unlimited, and the free account is enough to deploy. Server code is billed separately once you pass the free tier.

Should I use Cloudflare Pages or Workers?

Workers. Both Astro and Cloudflare recommend Workers for new projects. Pages is kept for sites that already use it.

Can I use my own domain?

Yes. Your domain needs to be managed by Cloudflare, then you add it to the Worker in the Cloudflare dashboard under Settings, Domains and Routes.