Deploying a Static Astro Site to Cloudflare Pages

An Astro site using static output produces deployable HTML, CSS, and JavaScript. A blog without server rendering can publish dist directly on Cloudflare Pages without an adapter. The essential deployment settings are the repository, build command, and output directory.

Configuration verified for this site

On September 11, 2026, this repository was built with Astro 7.3.2 and Node.js 22.22.2. At that time, astro.config.mjs defined site: 'https://app-hacks.net' and the sitemap integration, while relying on Astro’s default static output. The build generated 15 pages and dist/sitemap-index.xml. Cloudflare dashboard and DNS settings were outside that local verification.

Confirm static output

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://app-hacks.net',
  integrations: [sitemap()],
});

Set site so Astro can generate correct canonical and sitemap URLs. Then run the same build used in deployment:

npm ci
npm run build

Astro writes to dist by default. Do not commit this generated directory; letting Cloudflare rebuild it keeps source and output from becoming conflicting authorities.

Configure Git integration

Connect the GitHub or GitLab repository from Workers & Pages. If an Astro preset is available, select it and confirm the resulting values:

Production branch: main
Build command: npm run build
Build output directory: dist
Root directory: /

Change the root directory only when Astro truly lives in a monorepo subdirectory. Record the supported Node.js range in package.json and make the build environment satisfy it:

{
  "engines": { "node": ">=22.12.0" },
  "scripts": { "build": "astro build" }
}

Pushes to the production branch can deploy production, while other branches or pull requests can receive previews. A schema failure in npm run build stops the new deployment and leaves the previously successful deployment in place.

Diagnose failed builds

Read logs in order: dependency installation, Node.js version, then Astro content synchronization. If local npm install succeeds but cloud npm ci fails, check whether package-lock.json changed with the manifest. Never commit secrets. Values prefixed with PUBLIC_ may be embedded in static output, so client code must not reference private API keys.

Assign a custom domain

Add the domain from the Pages project’s Custom domains section. When DNS is in the same Cloudflare account, follow the records shown by the dashboard. With external DNS, use the Pages hostname Cloudflare provides. Do not guess an IP and pin an A record.

Choose one production host and redirect the other host to it. Astro’s site, page canonicals, and the sitemap URL in robots.txt must all use that final HTTPS origin. Wait until the domain is Active and its TLS certificate is ready before announcing it.

Verification and common failure points

Run nvm use to select Node.js 22.22.2 from this repository’s .nvmrc, then npm run build. On this site, Node.js 20.18.2 did not start the same build because Astro required 22.12.0 or later. Confirm dist/index.html, route HTML, sitemap, and canonical URLs. Use the dashboard-provided DNS values rather than inferred records.