Next.js Wildcard Subdomains — Smashing Magazine

Next.js Wildcard Subdomains

About The Author

Sam is a high school student in Singapore who enjoys using his weekends to build weird and wonderful side projects whilst also attempting to finish his …

More about
Sam ↬

Quick summary ↬

Hosting with a wildcard subdomain enables your users to visit your site on any subdomain of your domain (*, and as you can imagine, we can use this to create unique user experiences which we’ll be exploring in this article through a Next.js lens.

A “wildcard”? What in the world? Great question, these types of domain stem from Wildcard DNS Records which look like this:

When used, this DNS record will cause any subdomain that matches with the wildcard to hold a TXT value of: “Wild! You have found a wildcard.”

For example, if this was set on the domain, and would both return the above TXT value. The same principle can be applied to CNAME & A records as well.

Wild Use Cases For Wildcards

Wildcards can be used for a wide range of things. For now, let’s focus on where they can be applied in combination with Next.js:

The Caveats Of Wildcards With Next.js

Sigh. Unfortunately, using wildcards isn’t perfect there are a couple of drawbacks:

Building With Wildcards

With all this talk, let’s look at building with these domains. We’ll be focusing on three places where you can get the wildcard:

More after jump! Continue reading below ↓

Meet Smashing Online Workshops on front-end & UX, with practical takeaways, live sessions, video recordings and a friendly Q&A. On design systems, CSS/JS and UX. With Carie Fisher, Stefan Baumgartner and so many others.

Server Side In getServerSideProps

This is the most commonplace in which you will need to extract the wildcard, you can use this on pages where you need to render completely different content for different wildcards. As discussed above, this can not be done through static site generation so we must do it on server-side rendered pages.

The getServerSideProps is passed a context object, in this object you can access the HTTP request object using context.req. In this request object, you can access the hostname at, which will return a string such as We can split the string into an array across each period and then access the first item in said array. In code, that looks like this:

As you can see in this piece of code, we do an extra set processing on the wildcard if it’s the base domain we set the wildcard to home (if taking user input, this is a case you will need to handle) and if we are testing on localhost we can test out other wildcards. In our default export function, which renders our page we can use a switch statement to handle the wildcards:

Client Side With useEffect

If you only want to make small modifications to each page on a different wildcard, you can avoid using server-side rendering by using the useEffect hook on the client-side. This approach will be rather similar to how we did it in getServerSideProps, except we will be relying on window.location.hostname. Using window means that the initial server render won’t be able to access the information, so we must wrap it within a useEffect hook that runs on the client-side. Here’s how that code looks like:

This approach, however, is far from perfect as there is a delay between the page’s first render and the wildcard being available. Therefore, if you are making drastic changes based on the wildcard then the changes will be jarring for your user. This may also hurt your cumulative layout shift measure on your web vitals. With this in mind, I highly recommend limiting your use of this approach to adaptations that would be off-sight from the viewer on the initial load. An example would be a branded footer, on a technical documentation page. It is, of course, still handy to know.

Server Side On API Routes And Edge Functions

API routes are another area where you may want to access a wildcard from. Fortunately, the same request object we discussed in the above section on getServerSideProps is also available when using a Node.js API route with Next.js. We can access it like this:

Following this, we can then take certain actions such as fetching different data from your database depending on the wildcard and return that from the API.

This same logic can be applied to Next.js’ new Edge Functions / Middleware. This enables you to use wildcards in more than one route without duplicating code as well as speeding up the processing as code execution happens on the edge. Whilst the functionality is still in beta, it’s certainly something to keep an eye on.

The ?Aussie-izer

Now that we’ve explored the theory of this strategy, let’s explore how we put it into practice. In this section, we’ll be taking this approach to build a project that flips websites upside down (well, websites that are using a .com domain and aren’t subdomains) called the ?Aussie-izer.

To get started, we’re going to want to run yarn init and then yarn add next react react-dom, and finish up by adding these standard scripts to our package.json:

As soon as we’ve got a standard Next.js project set up, we’re going to want to create the only code file we’ll need for this project: pages/index.js.

First, we’ll want to add the getServerSideProps function in which we’ll extract the wildcard (as I’ll be hosting this at that’s what I’ll be evaluating to home as:

We’ll then be using that wildcard, to render an iFrame to fill that page (by flipping iFrame over to create the effect), with our src being set to {`https://${props.wildcard}.com`}. We’ll use a switch case, as we discussed above, to render a small helper page if they visit the home page:

export default function App(props) {
  switch (props.wildcard) {
    case "home":
      return (
          Welcome to the Aussie-izer! This only works for .com domains. If you
          want to Aussie-ize{" "}
          <a href=""></a> visit{" "}
          <a href="">
      return (
            transform: "rotate(180deg)",
            border: "none",
            height: "100vh",
            width: "100%",
            overflow: "hidden",

And we’re ready to go! The live version is available at and the source code can be found at


If you’re hosting on a custom server, wildcard domains will be a breeze to set up through DNS. However, a great part about using Jamstack is being able to host on services such as Vercel or Netlify; these services have their own domain management systems.

Vercel supports wildcard domains out of the box — for all accounts. To use them, first visit the Domains section of your deployment’s Settings tab. Next, you’ll want to enter your domain by using a * to signify the wildcard.

For the above example, I entered:

You most likely will also want to add your root domain (, in my case) to be able to provide a homepage or some instructions, however, that could also be a separate codebase.

Netlify limits their wildcards feature to Pro accounts; if you have a Pro account, you will need to email their support staff for them to then enable the option on your account. It will show up in the domain settings page once enabled.

Render also offers wildcard domains to all users. Simply enter a domain with a * (signifying your wildcard) in the Add Custom Domain input on the custom domains section of your site’s settings page which will enable the wildcard. Please note that Render will require you to add additional records to your DNS so that they can issue a LetsEncrypt SSL certificate (exact instructions will be shown to you when you input your wildcard domain).

That’s It!

Wildcard domains often go under the radar — I hope you enjoyed exploring them with me. Thank you!

Also: FYI Australians do not actually see upside down.

Further Reading On Smashing Magazine

Smashing Editorial
(vf, yk, il)

This content was originally published here.