How to Deploy a Next.js Static Site to DeployHQ Static Hosting

By Alex M · Posted on

Devops & Infrastructure, Frontend, and Tutorials

How to Deploy a Next.js Static Site to DeployHQ Static Hosting

DeployHQ Static Hosting is built for compiled output — exactly the shape Next.js produces when you enable static export. This guide walks through deploying a Next.js site to Static Hosting end to end: configure Next.js for static export, provision the site in DeployHQ, set up the build pipeline, point a custom domain at it, and ship the first deploy.

This is the static-export path — output: 'export' in next.config.js, no server-rendered routes, no edge middleware. If your app uses SSR, ISR, or App Router server components, Static Hosting isn't the right fit — use DeployHQ Managed VPS Hosting and run Node there, or see how to deploy Next.js on a VPS before choosing a platform with full Next.js runtime support.

What you'll build

By the end of this guide:

  • A Next.js project configured for static export
  • A DeployHQ project with Static Hosting connected to your repository
  • A working build pipeline that runs next build and uploads the export to Cloudflare's edge
  • The site serving from <subdomain>.deployhq-sites.com (and optionally a custom domain)
  • Atomic deploys on every push, with one-click rollback to any previous version

Expected time: under 10 minutes from a fresh project.

Prerequisites

  • A Next.js project (any recent version supporting output: 'export')
  • A Git repository the project lives in (GitHub, GitLab, or Bitbucket)
  • A DeployHQ account with beta features enabled (enable under Settings > Beta Features)
  • Node.js installed locally to test the build before pushing

If you don't have a DeployHQ account yet, start a free trial — the trial includes one Static Hosting site at no charge.

Step 1: Configure Next.js for static export

Open next.config.js (or next.config.mjs) at the project root and add output: 'export'. For most projects you'll also need images: { unoptimized: true } because the built-in Next.js Image Optimization API requires a Node runtime, which Static Hosting doesn't provide.

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  // optional: rewrite trailing slashes for nicer URLs
  // trailingSlash: true,
};

module.exports = nextConfig;

A few things this changes:

  • next build now produces a static export in out/ (rather than running a Node server)
  • Any route using getServerSideProps, server actions, route handlers, or middleware will fail the build — those need a runtime
  • next/image falls back to plain <img> rendering with no on-the-fly resizing

Run npm run build (or your equivalent) and confirm the out/ directory appears. Open out/index.html in a browser to sanity-check the build works locally.

For a deeper reference on Next.js deployment patterns generally, see the Next.js 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 — this is just for your reference; it doesn't affect the public URL
  2. Select Static Hosting from the protocol picker under the Hosting section
  3. Choose a subdomain — your site will be served at <subdomain>.deployhq-sites.com. Subdomains must be unique across all DeployHQ accounts. Lowercase letters, numbers, and hyphens only
  4. Set the subdirectory to deploy from to out (this is where Next.js writes the static export by default)
  5. Toggle SPA mode off — Next.js static export generates a separate HTML file per route, so client-side routing fallbacks aren't needed
  6. Click Create Server

DeployHQ also runs framework detection when you connect the repository. If a Next.js detected! callout appears at the top of Site Configuration with a recommended output directory, that's the rule-based detection picking up your next.config.js. You can override the suggested values before clicking Create — but for a stock static export, accepting them is fine.

Provisioning takes under a minute. Once the status flips to active, the site exists on the edge — but nothing's been deployed yet.

Step 3: Configure the build pipeline

DeployHQ runs your build before uploading the artifact to Cloudflare. For Next.js static export, the build pipeline needs two stages: install dependencies, then build.

In the project's build settings, add commands:

npm ci
npm run build

If your package.json has a custom build script, replace npm run build accordingly. The end result is that DeployHQ's build worker has an out/ directory matching what you'd see locally.

Common environment variables to set in DeployHQ's environment-variable UI:

  • NEXT_PUBLIC_API_URL — any public-prefixed env vars Next.js inlines into the bundle
  • NODE_ENV=production — usually set automatically but worth confirming for deterministic builds

Anything not prefixed with NEXT_PUBLIC_ won't appear in the static bundle (Next.js's standard behavior).

Step 4: First deploy

Push to your repository (or trigger a manual deployment from the DeployHQ dashboard). DeployHQ:

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

The deployment log streams each step. When it completes, visit https://<subdomain>.deployhq-sites.com and confirm the site renders.

If the build fails: check the log for the exact error. Most common Next.js static-export failures are (a) a route that uses server-only features (getServerSideProps, server actions), (b) next/image without unoptimized: true, or (c) a missing dependency the build needs.

Step 5: Add a custom domain

To serve from your own domain (e.g., docs.example.com):

  1. In your DNS provider, add a CNAME record pointing your subdomain to <subdomain>.deployhq-sites.com
  2. Wait for DNS propagation (usually minutes; sometimes longer depending on TTL)
  3. Cloudflare provisions an HTTPS certificate automatically once the CNAME resolves

That's it. Your site now serves from docs.example.com over HTTPS via Cloudflare's edge.

For an apex domain (example.com with no subdomain), you'll need either an ALIAS / ANAME record from your DNS provider (some providers support these) or a flattening service.

Common gotchas

The build succeeds but routes 404. Next.js static export generates HTML files based on detected routes. Dynamic routes ([slug].js) need generateStaticParams (App Router) or getStaticPaths (Pages Router) to enumerate which paths to render. Without that, the dynamic routes won't appear in the export.

Images aren't optimized. Static Hosting doesn't run code at request time, so next/image can't transform images on the fly. Options: pre-optimize images at build time with a tool like sharp or next-export-optimize-images, or use an external image CDN (Cloudflare Images, Imgix, Cloudinary).

API routes don't work. Static export doesn't include API routes — they require a Node runtime. Move API logic to a separate backend (DeployHQ Managed VPS, a serverless function on Cloudflare Workers, or any existing backend), or rearchitect to call third-party APIs directly from the client.

Server actions fail at build time. Same reason — actions need a server. For a fully static export, replace them with direct client-side fetches to an API endpoint.

Trailing slashes change URLs. Adding trailingSlash: true to next.config.js mid-project changes every route URL — set it intentionally at the start and don't toggle it later without redirects in place.

What you've shipped

You now have:

  • A Next.js static export rebuilding on every push
  • Atomic deploys with no downtime during the transfer
  • HTTPS over Cloudflare's edge with automatic certificate management
  • One-click rollback to any previous deployment via the DeployHQ dashboard

For the bigger picture of where Static Hosting fits among DeployHQ's hosting catalog, see the hosting hub. For a broader deployment walkthrough, see deploying static sites with DeployHQ. The Static Hosting pillar guide covers framework auto-detection, SPA mode, and the comparison against Vercel, Netlify, and Cloudflare Pages in more depth.

For a roundup of how DeployHQ Static Hosting fits alongside the rest of the deployment-tool category, our best software deployment tools in 2026 post is a useful reference. And for context on the broader DeployHQ proposition across all five hosting types it supports, see your universal deployment and hosting platform.

What's next

If your Next.js app outgrows static export — you need SSR, ISR, server actions, or edge middleware — you have two clean upgrade paths inside the same DeployHQ project:

  1. Move to DeployHQ Managed VPS and run a full Next.js Node process there. The same DeployHQ pipeline ships to either target; you swap the server type in the project, not the project itself.
  2. Keep Static Hosting for the marketing site, run the dynamic parts on a separate target. A separate Managed VPS or BYO server handles the API/SSR, and the static frontend continues to live on Cloudflare's edge.

Either way, the build pipeline you set up here doesn't change — DeployHQ's build is generic, the target is what swaps.

Start a free trial if you don't have an account yet, and the 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 Next.js + Static Hosting? Email support@deployhq.com or follow @deployhq on X for product updates.