Astro and [DeployHQ Static Hosting](https://www.deployhq.com/hosting/static) line up naturally. Astro's default mode produces a fully static site — HTML, CSS, JavaScript, and assets — which is exactly the shape Static Hosting is built to serve from Cloudflare's edge. This guide walks through deploying an Astro project end to end: confirm the static config, provision the site in [DeployHQ](https://www.deployhq.com), set up the build pipeline, add a custom domain, and ship.

If you've added an SSR adapter to Astro (Node, Vercel, Netlify, Cloudflare adapters) and you need server-rendered routes at request time, Static Hosting isn't the right surface — use [DeployHQ Managed VPS Hosting](https://www.deployhq.com/hosting/managed-vps) and run a Node process there, or keep using your existing SSR host.

## What you'll build

- An Astro project verified as static-output
- A [DeployHQ](https://www.deployhq.com) project with Static Hosting connected to your repository
- A build pipeline that runs `astro build` and uploads `dist/` to Cloudflare's edge
- The site live on `<subdomain>.deployhq-sites.com` (and optionally a custom domain)
- Atomic deploys on every push, with one-click rollback

Expected time: under 10 minutes from a fresh Astro project.

## Prerequisites

- An Astro project (any recent version)
- A Git repository the project lives in
- A [DeployHQ](https://www.deployhq.com) account with beta features enabled ( **Settings \> Beta Features** )
- Node.js installed locally to verify the build before pushing

If you don't have a [DeployHQ](https://www.deployhq.com) account, [start a free trial](https://www.deployhq.com/signup) — the trial includes one Static Hosting site at no charge.

## Step 1: Confirm Astro is producing static output

Astro defaults to static output. Open `astro.config.mjs` and verify `output` is either unset, set to `'static'`, or omitted entirely:

```
import { defineConfig } from 'astro/config';

export default defineConfig({
  // output defaults to 'static' when omitted
  // output: 'static',
});
```

Astro 5 removed `output: 'hybrid'` — `static` absorbed what hybrid used to do, and adding an adapter is now what lets individual routes render at request time via `export const prerender = false`. So if you previously added an adapter (`@astrojs/node`, `@astrojs/vercel`, etc.), check two things:

- `output: 'server'` — switch it to `output: 'static'` (this removes any SSR routes; they won't work on Static Hosting)
- Any route exporting `prerender = false` — flip it to `true` or drop the export, so every page is generated at build time

Run `npm run build` (which runs `astro build` by default). Astro writes the static export to `dist/`. Open `dist/index.html` to confirm the build succeeded locally.

For a deeper Astro reference on the deployment side, see [the Astro deployment guide](https://www.deployhq.com/guides/astro).

## Step 2: Provision a Static Hosting site in DeployHQ

In your [DeployHQ](https://www.deployhq.com) project, click **New Server** :

1. Enter a name for the server (for your reference only)
2. Select **Static Hosting** from the protocol picker under the **Hosting** section
3. Choose a subdomain — site will serve at `<subdomain>.deployhq-sites.com`. Lowercase letters, numbers, hyphens only
4. Set the **subdirectory to deploy from** to `dist` (Astro's default build output)
5. Toggle **SPA mode** _off_ — Astro pre-renders every route into a separate HTML file, so client-side routing fallbacks aren't needed
6. Click **Create Server**

If [DeployHQ](https://www.deployhq.com) detects Astro automatically when you connect the repo, a purple Astro detected! callout will appear at the top of Site Configuration with `dist` already filled in. You can override anything before clicking Create.

Provisioning usually takes under a minute. The site is now live on the edge — but empty until the first deploy completes.

## Step 3: Configure the build pipeline

[DeployHQ](https://www.deployhq.com) runs your build on its own infrastructure before uploading the result. The [build pipeline](https://www.deployhq.com/features/build-pipelines) needs two stages for Astro: install dependencies, then build.

In project build settings, add:

```
npm ci
npm run build
```

(Substitute `pnpm install --frozen-lockfile && pnpm build` or `yarn install --frozen-lockfile && yarn build` if your project uses a different package manager.)

Environment variables to set in DeployHQ's UI:

- `PUBLIC_*` — any env vars Astro inlines into the client bundle (Astro's convention is the `PUBLIC_` prefix)
- `NODE_ENV=production` — usually set automatically but worth confirming

Astro only inlines env vars prefixed `PUBLIC_` into the client bundle, mirroring Vite's behavior. Anything else stays server-side at build time and is stripped from the static output.

## Step 4: First deploy

Push to the configured branch (or trigger a manual deploy from the [DeployHQ](https://www.deployhq.com) dashboard). DeployHQ:

1. Clones the repo at HEAD
2. Runs the build pipeline (`npm ci && npm run build`)
3. Uploads the contents of `dist/` to object storage atomically
4. Flips the edge routing to serve the new version

Watch the deployment log stream. When it completes, visit `https://<subdomain>.deployhq-sites.com`. The Astro site should render.

If the build fails, the log shows the exact error. Most common Astro static-build failures:

- A page using `Astro.request` or server-only globals while running in static mode → make the page pre-renderable or move dynamic logic client-side
- A missing image / asset path → Astro requires assets in the right relative location for the build to resolve them
- A content-collection schema mismatch → Astro will refuse to build if frontmatter doesn't match the defined schema

## Step 5: Add a custom domain

To serve from your own domain (`blog.example.com`, `docs.example.com`):

1. In your DNS provider, create a `CNAME` record pointing your subdomain to `<subdomain>.deployhq-sites.com`
2. Wait for DNS propagation
3. Cloudflare provisions an HTTPS certificate automatically once the CNAME resolves

For an apex domain (`example.com`), use ALIAS / ANAME if your DNS provider supports it, or a flattening service.

## Common gotchas

**View transitions don't trigger.** Astro's view transitions need both the source and destination page to be Astro-rendered. If you link from an Astro page to a non-Astro page (or vice versa), the transition will skip. Confirm both ends are in your Astro site.

**Content collections re-fetch on every build.** If your content collection sources remote data (RSS feeds, external CMSes), every deploy refetches at build time. That's usually desired for freshness but can slow build pipelines. Cache the data or pre-build outside [DeployHQ](https://www.deployhq.com) if rebuild time matters.

**`Astro.glob()` paths in production differ from dev.** Astro resolves globs at build time. If your glob pattern depends on environment-specific paths or env vars, what worked in `astro dev` may not match production. Verify with a local `astro build` before pushing.

**Image optimization on `<Image>` components.** Astro's built-in image optimization uses `sharp` at build time, which DeployHQ's build pipeline supports. If image transforms fail in the build log, check that sharp is installed and that your image sources are accessible during the build.

**Trailing slashes change canonical URLs.** Astro's `trailingSlash` setting in `astro.config.mjs` affects how URLs render in the built `dist/`. Set it intentionally at the project start; changing later will require redirects to avoid breaking external links.

## What you've shipped

You now have:

- An Astro static export rebuilding on every push
- Atomic deploys with no downtime during the transfer
- HTTPS over Cloudflare's edge with automatic certificate management
- [Zero-downtime atomic transfers](https://www.deployhq.com/features/zero-downtime-deployments) and one-click rollback via the [DeployHQ](https://www.deployhq.com) dashboard

For background on where Static Hosting fits in DeployHQ's catalog, the [hosting hub](https://www.deployhq.com/hosting) covers the full set of options. The [Static Hosting pillar guide](https://www.deployhq.com/blog/static-hosting-on-deployhq) goes deeper on framework auto-detection and SPA mode, and the head-to-heads cover [Static Hosting against Cloudflare Pages](https://www.deployhq.com/blog/deployhq-static-hosting-vs-cloudflare-pages) and [Static Hosting against Netlify](https://www.deployhq.com/blog/deployhq-static-hosting-vs-netlify) in detail.

For a roundup placing [DeployHQ](https://www.deployhq.com) Static Hosting alongside the rest of the deployment-tool category, see [best software deployment tools in 2026](https://www.deployhq.com/blog/best-software-deployment-tools). For the wider [DeployHQ](https://www.deployhq.com) story across all five hosting types, [your universal deployment and hosting platform](https://www.deployhq.com/blog/deployhq-your-universal-deployment-platform-for-all-hosting-types) is the bridge post.

## What's next

If your Astro project picks up SSR routes — content that genuinely needs to render at request time — you have two upgrade paths within the same [DeployHQ](https://www.deployhq.com) project:

1. **Switch the Astro project to a Node adapter and move to [DeployHQ](https://www.deployhq.com) Managed VPS.** The Node adapter runs `astro build` in server mode; Managed VPS runs the resulting Node service. Same [DeployHQ](https://www.deployhq.com) pipeline, different server type.
2. **Split the static and dynamic surfaces.** Marketing pages, blog posts, docs stay on Static Hosting; the dynamic bits run separately on Managed VPS or any BYO server, and both ship from the same [DeployHQ](https://www.deployhq.com) project.

Either way, the build pipeline you set up here keeps working — DeployHQ's build pipeline is generic; only the deployment target changes.

[Check the current plans](https://www.deployhq.com/pricing) if you don't have an account yet — the trial's included Static Hosting site is enough to ship this guide end to end. For the full Static Hosting product reference, see the [Static Hosting support library](https://www.deployhq.com/support/servers/static-hosting).

* * *

Questions or feedback on Astro + Static Hosting? Email [support@deployhq.com](mailto:support@deployhq.com) or follow [@deployhq](https://x.com/deployhq) on X for product updates.