Custom Domains

Configure custom domains in your components.

You can configure custom domains for your frontends or APIs in SST. By default, these components auto-generate a URL. You can pass in the domain to use your custom domain.

new sst.aws.Nextjs("MyWeb", {
  domain: "example.com"
});

SST supports a couple of DNS providers automatically. These include AWS Route 53, Cloudflare, and Vercel. Other providers will need to be manually configured.

Let’s look at how it works.

How it works

Configuring a custom domain is a two step process.

Validate that you own the domain. For AWS you do this by creating an ACM certificate and validating it by:
- Setting a DNS record with your domain provider.
- Verifying through an email sent to the domain owner.
Add the DNS records to route your domain to your component.

SST can perform these steps automatically for the supported providers through a concept of adapters. These create the above DNS records on a given provider.

Adapters

You can use a custom domain hosted on any provider. SST supports domains on AWS, Cloudflare, and Vercel automatically.

AWS

By default, if you set a custom domain, SST assumes the domain is configured in AWS Route 53 in the same AWS account.

{
  domain: {
    name: "example.com"
  }
}

This is the same as using the sst.aws.dns adapter.

{
  domain: {
    name: "example.com",
    dns: sst.aws.dns()
  }
}

If you have the same domain in multiple hosted zones in Route 53, you can specify the hosted zone.

{
  domain: {
    name: "example.com",
    dns: sst.aws.dns({
      zone: "Z2FDTNDATAQYW2"
    })
  }
}

If your domains are hosted on AWS but in a separate AWS account, you’ll need to follow the manual setup.

Vercel

If your domains are hosted on Vercel, you’ll need to do the following.

Add the Vercel provider to your app.
Terminal window
```
sst add @pulumiverse/vercel
```
Set the VERCEL_API_TOKEN in your environment. You might also need to set the VERCEL_TEAM_ID if the domain belongs to a team.
Terminal window
```
export VERCEL_API_TOKEN=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa
```

Use the sst.vercel.dns adapter.

{
  domain: {
    name: "example.com",
    dns: sst.vercel.dns()
  }
}

Cloudflare

If your domains are hosted on Cloudflare, you’ll need to do the following.

Add the Cloudflare provider to your app.
Terminal window
```
sst add cloudflare
```

Set the CLOUDFLARE_API_TOKEN in your environment.

export CLOUDFLARE_API_TOKEN=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa
export CLOUDFLARE_DEFAULT_ACCOUNT_ID=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa

Use the sst.cloudflare.dns adapter.

{
  domain: {
    name: "example.com",
    dns: sst.cloudflare.dns()
  }
}

Manual setup

If your domain is on a provider that is not supported above, or is in a separate AWS account; you’ll need to verify that you own the domain and set up the DNS records on your own.

To manually set up a domain on an unsupported provider, you’ll need to:

Validate that you own the domain by creating an ACM certificate. You can either validate it by setting a DNS record or by verifying an email sent to the domain owner.

For CloudFront distributions, the certificate needs to be created in us-east-1.

If you are configuring a custom domain for a CloudFront distribution, the ACM certificate that’s used to prove that you own the domain needs be created in the us-east-1 region.

For all the other components, like ApiGatewayV2 or Cluster, can be created in any region.

Once validated, set the certificate ARN as the cert and set dns to false.

{
  domain: {
    name: "domain.com",
    dns: false,
    cert: "arn:aws:acm:us-east-1:112233445566:certificate/3a958790-8878-4cdc-a396-06d95064cf63"
  }
}

Add the DNS records in your provider to point to the CloudFront distribution, API Gateway, or load balancer URL.