How to Deploy an Astro Site to DeployHQ Static Hosting

By Alex M · Posted on

Devops & Infrastructure, Frontend, and Tutorials

How to Deploy an Astro Site to DeployHQ Static Hosting

Astro and DeployHQ Static Hosting 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, 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 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 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 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 account, start a free trial — 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.

Step 2: Provision a Static Hosting site in DeployHQ

In your DeployHQ 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 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 runs your build on its own infrastructure before uploading the result. The build pipeline 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 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 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 and one-click rollback via the DeployHQ dashboard

For background on where Static Hosting fits in DeployHQ's catalog, the hosting hub covers the full set of options. The Static Hosting pillar guide goes deeper on framework auto-detection and SPA mode, and the head-to-heads cover Static Hosting against Cloudflare Pages and Static Hosting against Netlify in detail.

For a roundup placing DeployHQ Static Hosting alongside the rest of the deployment-tool category, see best software deployment tools in 2026. For the wider DeployHQ story across all five hosting types, your universal deployment and hosting platform 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 project:

  1. Switch the Astro project to a Node adapter and move to DeployHQ Managed VPS. The Node adapter runs astro build in server mode; Managed VPS runs the resulting Node service. Same DeployHQ 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 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 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.

Questions or feedback on Astro + Static Hosting? Email support@deployhq.com or follow @deployhq on X for product updates.