How to Deploy an Astro Site to Cloudflare Workers

Cloudflare Workers is where this site lives. So these are the exact steps we used. To deploy means to put your site online. You need a free Cloudflare account and a finished Astro site.

Step 1: Install Wrangler

Wrangler is Cloudflare’s command-line tool. That means you run it from your terminal. Add it to your project:

npm install wrangler@latest --save-dev

Step 2: Make a settings file

Make a file called wrangler.jsonc in your project folder. Put it 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. Log in to Cloudflare there. After that, it uploads your dist folder. Then it prints your new address. The address ends in workers.dev.

Open it. Your site is online.

Step 4: Make updates

Each 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 on its own from GitHub

Is your project on GitHub? Then Cloudflare can build and deploy it for you on every push. A push is when you send your changes up to GitHub. In the Cloudflare dashboard, go to Compute, then Workers & Pages. Create an application. Import your repository. Set the build command to npx astro build. Set the deploy command to npx wrangler deploy.

We have not set this up for Astro Nursery 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. Check that directory points to ./dist.
• Old pages 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 docs say requests for static files are free and unlimited. The free account is enough to deploy. Server code is billed on its own once you pass the free tier.

Should I use Cloudflare Pages or Workers?

Workers. Both Astro and Cloudflare suggest 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: go to Settings, then Domains and Routes.