[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, 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` over HTTPS
- 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: Your site's hostname

Your site serves from `<subdomain>.deployhq-sites.com` over HTTPS, with certificates managed automatically at Cloudflare's edge. There is nothing to configure — the hostname is live as soon as the first deploy finishes.

You can rename the subdomain at any time from the site's settings. The new hostname takes effect immediately and the old one starts returning a 404 straight away, with no redirect, so update anything pointing at it before you rename. Each site is limited to one rename every 24 hours.

Custom domains aren't available on Static Hosting yet — sites serve from their `deployhq-sites.com` hostname. If serving from your own domain matters for your project, email [support@deployhq.com](mailto:support@deployhq.com) and say so; customer demand is what drives what gets built next here.

## 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.

