Next.js Wildcard Subdomains — Smashing Magazine

What Wildcard Subdomains Unlock in Next.js

Wildcard DNS records let any subdomain of your domain resolve to the same server. Instead of registering each hostname individually, *.example.com catches everything from apples.example.com to oranges.example.com. For Next.js applications, this opens the door to per-tenant experiences, hosted portfolios, or playful experiments — all served from a single codebase.

In practice, a wildcard record simply assigns a value (often a TXT, CNAME, or A record) to any matching subdomain. The pattern is common for SaaS platforms where each customer gets their own namespace, such as domspizzeria.menus.abc alongside magicalprata.menus.abc. Each subdomain acts as an independent website with its own customizations.

Before diving in, weigh the constraints. Wildcard domains do not work with static site generation or incremental static regeneration — there is no clean way to pre-build pages per unknown subdomain. Local development also adds friction because localhost won't naturally simulate arbitrary subdomains. And while Vercel supports wildcards for all accounts, Netlify restricts the feature to Pro customers, and some other Jamstack hosts omit it entirely.

Reading the Wildcard on the Server

The most direct approach is to extract the subdomain inside getServerSideProps. The context object exposes the HTTP request, where context.req.headers.host returns something like example.yourdomain.com. Splitting on periods and taking the first segment gives you the wildcard value.

export async function getServerSideProps(context) {
  let wildcard = context.req.headers.host.split(".")[0];
  wildcard =
    wildcard != "yourdomain"
      ? process.env.NODE_ENV != "development"
        ? wildcard
        : process.env.TEST_WILDCARD
      : "home";
  return { props: { wildcard } };
}

Edge cases matter here. If the request hits the base domain, the first segment may be empty or unexpected; the snippet above normalizes that to home. It also handles localhost testing by allowing a hardcoded wildcard. Downstream, a switch statement in the page component can render different content for each value.

export default function App(props) {
  switch(props.wildcard) {
    case "home":
      return <div>Welcome to the home page!</div>;
      break;
    default:
      return <div>The wild card is: {props.wildcard}.</div>;
  }
}

Client-Side Detection with useEffect

When the changes per wildcard are minor, you can skip server-side rendering and read the hostname in the browser via window.location.hostname. Since window is unavailable during the initial server render, the logic must run inside a useEffect hook.

// useEffect and useState must be imported from 'react'

const [wildcard, setWildcard] = useState("")
  useEffect(() => {
    setWildcard(window.location.hostname.split(".")[0])
  }, [])

This pattern has a visible drawback: there is a short delay between first paint and the wildcard being applied. For anything that shifts the layout dramatically, that lag hurts both user experience and Cumulative Layout Shift scores. Reserve this approach for subtle, below-the-fold adaptations — for instance, swapping a footer brand — rather than restructuring the whole page.

Wildcards in API Routes and Edge Middleware

Node.js API routes receive the same request object, so hostname parsing works identically. You can read the wildcard, fetch tenant-specific data from a database, and return the result without involving the page layer.

export default (req, res) => {
  let wildcard = req.headers.host.split(".")[0];
  wildcard =
    wildcard != "yourdomain"
      ? process.env.NODE_ENV != "development"
        ? wildcard
        : process.env.TEST_WILDCARD
      : "home";
  res.json({ wildcard: wildcard })
}

The logic also carries over to Next.js middleware and edge functions. Running at the edge, code can inspect the wildcard across many routes without duplication, and response times improve because execution is closer to the user. Edge support is still maturing, but it is worth watching for production use.

// _middleware.js
export function middleware(req) {
  let wildcard = req.headers.get("host").split(".")[0];
  console.log(wildcard);
  wildcard =
    wildcard != "yourdomain"
      ? process.env.NODE_ENV != "development"
        ? wildcard
        : process.env.TEST_WILDCARD
      : "home";
  console.log(process.env.TEST_WILDCARD);
  return new Response(JSON.stringify({ wildcard: wildcard }), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
}

Building a Wildcard-Powered Web Toy

To show the concept end to end, the article walks through a small project: the 🦘 Aussie-izer. It flips any *.com website upside down — a playful nod to Australians, who are, the author reassures, not actually upside down. Hosted at aussieizer.sampoder.com, the demo treats its own subdomains as targets.

Setup is minimal beyond the standard scripts:

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "next lint"
}

All logic lives in a single file, pages/index.js. First, getServerSideProps extracts the wildcard, treating the bare aussieizer.sampoder.com domain as home:

export async function getServerSideProps(context) {
  let wildcard = context.req.headers.host.split(".")[0];
  wildcard =
    wildcard != "aussieizer"
      ? wildcard != "localhost:3000"
        ? wildcard
        : process.env.TEST_WILDCARD
      : "home";
  return { props: { wildcard } };
}

The page then renders an iframe pointed at https://${props.wildcard}.com, flipping the iframe with CSS to invert the target site. A switch statement provides a small helper page for the root domain instead.

export default function App(props) {
  switch (props.wildcard) {
    case "home":
      return (
        <div>
          Welcome to the Aussie-izer! This only works for .com domains. If you
          want to Aussie-ize{" "}
          <a href="https://example.com">https://example.com</a> visit{" "}
          <a href="https://example.aussieizer.sampoder.com">
            https://example.aussieizer.sampoder.com
          </a>.
        </div>
      );
      break;
    default:
      return (
        <iframe
          src={`https://${props.wildcard}.com`}
          style={{
            transform: "rotate(180deg)",
            border: "none",
            height: "100vh",
            width: "100%",
            overflow: "hidden",
          }}
          frameBorder="0"
          scrolling="yes"
          seamless="seamless"
          height="100%"
          width="100%"
        ></iframe>
      );
  }
}

The working demo lives at aussieizer.sampoder.com, with source code on GitHub.

Configuring Wildcard Domains Across Hosts

On a custom server, wildcard DNS is straightforward. Jamstack hosts add their own management layers, with varying support.

Vercel

Vercel supports wildcard domains on every account. In the Settings tab, open Domains and enter the domain with a leading *. For the demo, the entry looks like:

*.aussieizer.sampoder.com

Adding the root domain separately is a good idea so visitors who hit the bare domain get a homepage or instructions rather than a broken page.

Netlify

Wildcards on Netlify require a Pro plan. Even then, you must contact support to enable the feature on your account; it appears in domain settings only after they activate it.

Render

Render offers wildcard domains to all users. In the custom domains section of your site settings, add a domain with a * prefix. Render will show additional DNS records needed to issue a Let's Encrypt SSL certificate, so follow those instructions closely.