Skip to content

Deploy your Astro Site to Cloudflare

How to deploy your Astro site to the web using Cloudflare

You can deploy full-stack applications, including front-end static assets and back-end APIs, as well as on-demand rendered sites, to Cloudflare Workers.

Prerequisites

Section titled “Prerequisites”

To get started, you will need:

  • A Cloudflare account. If you don’t already have one, you can create a free Cloudflare account during the process.

Cloudflare Workers

Section titled “Cloudflare Workers”

How to deploy with Wrangler

Section titled “How to deploy with Wrangler”

After your assets are uploaded, Wrangler will give you a preview URL to inspect your site.

How to deploy with CI/CD

Section titled “How to deploy with CI/CD”

You can also use a CI/CD system such as Workers Builds to automatically build and deploy your site on push.

If you’re using Workers Builds:

Troubleshooting

Section titled “Troubleshooting”

404 behavior

Section titled “404 behavior”

For Workers projects, you will need to set not_found_handling if you want to serve a custom 404 page. You can read more about this in the Routing behavior section of Cloudflare’s documentation.

wrangler.jsonc
{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

Client-side hydration

Section titled “Client-side hydration”

Client-side hydration may fail as a result of Cloudflare’s Auto Minify setting. If you see Hydration completed but contains mismatches in the console, make sure to disable Auto Minify under Cloudflare settings.

Node.js runtime APIs

Section titled “Node.js runtime APIs”

If you are building a project that is using on-demand rendering with the Cloudflare adapter and the server fails to build with an error message such as [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.:

  • This means that a package or import you are using in the server-side environment is not compatible with the Cloudflare runtime APIs.

  • If you are directly importing a Node.js runtime API, please refer to the Astro documentation on Cloudflare’s Node.js compatibility for further steps on how to resolve this.

  • If you are importing a package that imports a Node.js runtime API, check with the author of the package to see if they support the node:* import syntax. If they do not, you may need to find an alternative package.

← Docs Vault