[DeployHQ Static Hosting](https://www.deployhq.com/hosting/static) 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](https://www.deployhq.com), 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](https://www.deployhq.com/hosting/managed-vps) and run Node there, or see [how to deploy Next.js on a VPS](https://www.deployhq.com/blog/deploy-nextjs-on-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](https://www.deployhq.com) 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](https://www.deployhq.com) 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](https://www.deployhq.com) account yet, [start a free trial](https://www.deployhq.com/signup) — 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](https://www.deployhq.com/guides/next).

## 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 — 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](https://www.deployhq.com) 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](https://www.deployhq.com) 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](https://www.deployhq.com) runs your build before uploading the artifact to Cloudflare. For Next.js static export, the [build pipeline](https://www.deployhq.com/features/build-pipelines) 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](https://www.deployhq.com) 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](https://www.deployhq.com) dashboard

For the bigger picture of where Static Hosting fits among DeployHQ's hosting catalog, see the [hosting hub](https://www.deployhq.com/hosting). For a broader deployment walkthrough, see [deploying static sites with DeployHQ](https://www.deployhq.com/blog/using-deployhq-to-build-your-static-site). The [Static Hosting pillar guide](https://www.deployhq.com/blog/static-hosting-on-deployhq) covers framework auto-detection, SPA mode, and the comparison against Vercel, Netlify, and Cloudflare Pages in more depth.

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

## 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](https://www.deployhq.com) project:

1. **Move to [DeployHQ](https://www.deployhq.com) Managed VPS** and run a full Next.js Node process there. The same [DeployHQ](https://www.deployhq.com) 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](https://www.deployhq.com/signup) 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](https://www.deployhq.com/support/servers/static-hosting).

* * *

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