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.
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.
This is the same as using the sst.aws.dns
adapter.
If you have the same domain in multiple hosted zones in Route 53, you can specify the hosted zone.
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.
-
Set the
VERCEL_API_TOKEN
in your environment. You might also need to set theVERCEL_TEAM_ID
if the domain belongs to a team. -
Use the
sst.vercel.dns
adapter.
Cloudflare
If your domains are hosted on Cloudflare, you’ll need to do the following.
-
Add the Cloudflare provider to your app.
-
Set the
CLOUDFLARE_API_TOKEN
in your environment. -
Use the
sst.cloudflare.dns
adapter.
Manual setup
If your domain is on a provider that is not supported above, or is a separate AWS account; you’ll need 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.
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 setdns
tofalse
. -
Add the DNS records in your provider to point to the CloudFront distribution, API Gateway, or load balancer URL.