Next.js 16 custom domains guide

1. Match a hostname to a customer locally

Every browser request includes a Host header. Next.js 16’s proxy.ts is a convenient place to normalize that value once and pass it to the App Router.

Start with two .localhost names, which resolve to the loopback interface. Delete any client-supplied copy of the internal header before setting it yourself.

proxy.ts

The examples call a customer’s account a Tenant. Use your existing account, workspace, or organization model wherever you see that name.

import { NextResponse, type NextRequest } from "next/server"

export function proxy(request: NextRequest) {
  const requestHeaders = new Headers(request.headers)
  requestHeaders.delete("x-tenant-host")

  const hostname = cleanRequestHost(request.headers.get("host"))
  if (hostname) requestHeaders.set("x-tenant-host", hostname)

  return NextResponse.next({ request: { headers: requestHeaders } })
}

function cleanRequestHost(value: string | null) {
  return value?.trim().toLowerCase().replace(/:\d+$/, "") || null
}

Read the header in a server component. The small map below is only for this first local check; step five replaces it with your database.

import { headers } from "next/headers"
import { notFound } from "next/navigation"

const localDomains = new Map([
  ["alpha.localhost", { name: "Alpha Publishing" }],
  ["beta.localhost", { name: "Beta Studio" }],
])

export default async function Home() {
  const hostname = (await headers()).get("x-tenant-host")
  const tenant = hostname ? localDomains.get(hostname) : null
  if (!tenant) notFound()

  return <main><h1>{tenant.name}</h1></main>
}

curl -H 'Host: alpha.localhost:3000' http://127.0.0.1:3000/
curl -H 'Host: beta.localhost:3000' http://127.0.0.1:3000/
curl -i -H 'Host: unknown.localhost:3000' http://127.0.0.1:3000/

Checkpoint: the first two requests show different customer content, and the unknown hostname returns 404. No DNS or certificate work is needed yet.

2. Save each customer’s domains

A domain belongs in your own data model. Attach it to the signed-in customer, store one normalized hostname, and enforce global uniqueness so two customers cannot claim the same name.

SQLite keeps this example small. Use your existing database in a real app and keep the same constraints.

CREATE TABLE custom_domains (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  tenant_id INTEGER NOT NULL REFERENCES tenants(id),
  hostname TEXT NOT NULL UNIQUE,
  status TEXT NOT NULL DEFAULT 'pending',
  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);

Normalize configured domains more carefully than the quick local helper: lowercase them, remove one trailing dot, convert internationalized labels to ASCII, and reject URLs, ports, IP addresses, wildcards, local names, and malformed labels.

Create the row from a Server Action or route handler that gets the customer from your existing session. Never accept a customer ID from the form.

"use server"

export async function addDomain(formData: FormData) {
  const tenant = await requireCurrentTenant()
  const hostname = normalizeConfiguredHostname(
    String(formData.get("hostname") || ""),
  )

  await db.prepare(
    "INSERT INTO custom_domains " +
    "(tenant_id, hostname, status) VALUES (?, ?, 'pending')",
  ).run(tenant.id, hostname)
}

Keep this form on your normal app hostname. Next.js Server Actions compare the request origin with the host to help prevent cross-site form submissions; configure serverActions.allowedOrigins only when a trusted reverse proxy requires an additional control-panel origin.

Checkpoint: each signed-in customer can reserve a valid hostname, duplicates are rejected, and no customer can choose another customer’s ID.

3. Connect DNS and HTTPS

The hostname is reserved in your app. Now it needs a path to the server or service that receives traffic for Next.js. Give the customer the exact DNS record from that setup.

• Subdomains: docs.example.com can usually use a CNAME pointing at a stable hostname you operate.
• Apex (root) domains: example.com needs an A record for IPv4. If you support these domains, give customers a stable IPv4 address that keeps routing to your app.
• CNAME flattening: many DNS providers don't support it at the apex. It's best to support A records so customers don't need that feature. Cloudflare's flattening documentation explains how this provider-specific option works.
• IPv6: add an AAAA record as well if your receiving service offers stable IPv6.

A reverse proxy is a server in front of Next.js that accepts browser traffic and forwards it to your app. Whether you use one or a hosting platform, the receiving service needs to accept the customer hostname and preserve the original Host header.

You’ll probably want to check that DNS points directly or indirectly to the service receiving traffic for your app. Tools and managed services can make DNS setup and HTTPS much easier; see the bonus section below for one option.

HTTPS comes next. The browser completes TLS before Next.js sees the request, so the receiving service must issue a certificate for every customer hostname and renew it before it expires. Once DNS reaches that service and its certificate is ready, your server-side integration can move the saved row from pending to active.

curl -I https://customer.example

Checkpoint: the customer’s hostname reaches your receiving service over HTTPS, and Next.js still receives the original hostname.

4. Serve the customer’s pages

Replace both shortcuts from step one. Move hostname parsing into lib/domain.ts so incoming hosts and saved domains share lowercase, IDNA-to-ASCII, label validation, and trailing-dot handling. The request helper may strip a valid port and allow .localhost only in development; the configured-domain helper must still reject ports and local names.

Import that canonical request helper from proxy.ts in place of cleanRequestHost:

import { normalizeRequestHost } from "@/lib/domain"

// After deleting any client-supplied x-tenant-host:
const hostname = normalizeRequestHost(request.headers.get("host"))
if (hostname) requestHeaders.set("x-tenant-host", hostname)

Then replace the demo map with an exact database lookup. The db and CustomerSite imports below point to your existing database module and customer page component.

app/page.tsx

import { headers } from "next/headers"
import { notFound } from "next/navigation"
import { CustomerSite } from "@/app/components/customer-site"
import { db } from "@/lib/db"

export const dynamic = "force-dynamic"
export const revalidate = 0

export default async function CustomerPage() {
  const hostname = (await headers()).get("x-tenant-host")
  if (!hostname) notFound()

  const tenant = db.prepare([
    "SELECT tenants.* FROM custom_domains",
    "JOIN tenants ON tenants.id = custom_domains.tenant_id",
    "WHERE custom_domains.hostname = ?",
    "AND custom_domains.status = 'active'",
  ].join(" ")).get(hostname)

  if (!tenant) notFound()
  return <CustomerSite tenant={tenant} />
}

Keep management and login pages on your normal app hostname. In proxy.ts, return 404 when a custom hostname requests control paths such as /dashboard or /api/domains; check against an explicit set of normal app hosts. Leave public page and asset paths available. A custom hostname selects public content and never authorizes account changes.

If a trusted ingress cannot preserve Host, have it overwrite a dedicated hostname header and authenticate the connection before your app accepts that header.

Dynamic rendering avoids putting one customer’s page in a shared full-route cache. If you add caching later, include the normalized hostname in every cache key. Build absolute links from the saved domain, and keep session cookies host-only unless you have a specific reason to widen their scope.

Checkpoint: active domains render the right customer, while unknown, pending, and removing domains return 404.

5. Remove a domain safely

Stop routing before asking your hosting layer to detach the hostname and certificate. Keep the database row while that work is in progress so another customer cannot claim the same name during a retry.

export async function beginDomainRemoval(hostnameInput: string) {
  const tenant = await requireCurrentTenant()
  const hostname = normalizeConfiguredHostname(hostnameInput)
  const row = await findOwnedDomain(tenant.id, hostname)
  if (!row) throw new Error("Domain not found")

  const alreadyRemoving = row.status === "removing"
  const changed = alreadyRemoving || await markRemovingIfCurrent({
    id: row.id,
    tenantId: tenant.id,
    hostname,
    from: ["pending", "active"],
  })
  if (!changed) throw new Error("Domain changed; reload and try again")

  // Your hosting adapter owns this retry-safe operation.
  await hosting.removeHostname(hostname)
  return { status: "removing" }
}

The hosting call above is an explicit integration point, not a Next.js API. Implement it with your chosen platform’s hostname-removal operation, and make that operation safe to retry.

Treat timeouts as unknown outcomes. Leave the row in removing and retry the same cleanup. After the hosting layer confirms it no longer accepts the hostname, delete with a condition on the original row ID, customer ID, hostname, and removing status.

Those conditions protect a replacement row from a delayed response. Never turn routing back on just because a removal request failed.

Checkpoint: removal immediately returns 404, retries keep the hostname reserved, and the row disappears only after infrastructure cleanup is confirmed.