Deploying Astro to Cloudflare Workers

A static Astro build, uploaded as Worker assets, with one small script in front for API routes.

astrocloudflaredeployment

There are two ways to put an Astro site on Cloudflare Workers, and the simpler one is easy to talk yourself out of.

The first is the Cloudflare adapter, which compiles Astro’s server output into a Worker. You need it for on-demand rendering: server islands, form handlers, anything that has to run per request.

The second is to build the site statically and upload dist/ as the Worker’s static assets. That is what this site does.

The configuration

Static output, no adapter:

// astro.config.mjs
import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";

export default defineConfig({
  site: "https://cfw.azuredevops.xyz",
  output: "static",
  integrations: [mdx()],
});

Then point Wrangler at the build output rather than a hand-written public/:

{
  "main": "worker/index.js",
  "build": { "command": "npm run build" },
  "assets": { "directory": "./dist", "binding": "ASSETS" }
}

The build.command matters. Wrangler runs it before uploading, so a deploy always ships a fresh build instead of whatever happened to be sitting in dist/ from your last local run.

Where the Worker still earns its place

Static assets answer static paths. Anything else goes to the Worker:

export default {
  async fetch(request, env) {
    const { pathname } = new URL(request.url);

    if (pathname === "/api/health") {
      return Response.json({ status: "ok" });
    }

    return env.ASSETS.fetch(request);
  },
};

Node version

Astro 7 requires Node 22.12 or newer. Workers Builds will happily run an older default and fail somewhere confusing in the middle of the build, so pin it with a .node-version file at the repository root and stop thinking about it.


← All posts