Router
Reference doc for the `sst.aws.Router` component.
The Router
component lets you use a CloudFront distribution to direct requests to various parts of your application.
The routes
prop can route requests to function URLs, different domains, or any component that has an associated URL.
Minimal example
Route to a function URL
Route all API requests separately
Add a custom domain
Constructor
Parameters
-
name
string
-
args
RouterArgs
-
opts?
ComponentResourceOptions
RouterArgs
domain?
Type Input
<
string
|
Object
>
Set a custom domain for your Router.
Automatically manages domains hosted on AWS Route 53, Cloudflare, and Vercel. For other
providers, you’ll need to pass in a cert
that validates domain ownership and add the
DNS records.
By default this assumes the domain is hosted on Route 53.
For domains hosted on Cloudflare.
Specify a www.
version of the custom domain.
domain.aliases?
Type Input
<
string
[]
>
Alias domains that should be used. Unlike the redirect
option, this keeps your visitors
on this alias domain.
So if your users visit app2.domain.com
, they will stay on app2.domain.com
in their
browser.
domain.cert?
Type Input
<
string
>
The ARN of an ACM (AWS Certificate Manager) certificate that proves ownership of the domain. By default, a certificate is created and validated automatically.
The certificate will be created in the us-east-1
region as required by AWS CloudFront.
If you are creating your own certificate, you must also create it in us-east-1
.
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.
- 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 URL.
domain.dns?
Type Input
<
false
|
sst.aws.dns
|
sst.cloudflare.dns
|
sst.vercel.dns
>
Default sst.aws.dns
The DNS provider to use for the domain. Defaults to the AWS.
Takes an adapter that can create the DNS records on the provider. This can automate validating the domain and setting up the DNS routing.
Supports Route 53, Cloudflare, and Vercel adapters. For other providers, you’ll need
to set dns
to false
and pass in a certificate validating ownership via cert
.
Specify the hosted zone ID for the Route 53 domain.
Use a domain hosted on Cloudflare, needs the Cloudflare provider.
Use a domain hosted on Vercel, needs the Vercel provider.
domain.name
Type Input
<
string
>
The custom domain you want to use.
Can also include subdomains based on the current stage.
domain.redirects?
Type Input
<
string
[]
>
Alternate domains to be used. Visitors to the alternate domains will be redirected to the
main name
.
Use this to create a www.
version of your domain and redirect visitors to the apex domain.
invalidation?
Type Input
<
boolean
|
Object
>
Default Invalidation is turned off
Configure how the CloudFront cache invalidations are handled.
Enable invalidations. Setting this to true
will invalidate all paths. It is equivalent
to passing in { paths: ["/*"] }
.
invalidation.paths?
Type Input
<
Input
<
string
>
[]
>
Default [”/*”]
Specify an array of glob pattern of paths to invalidate.
Invalidate the index.html
and all files under the products/
route. This counts as two invalidations.
invalidation.token?
Type Input
<
string
>
Default A unique value is auto-generated on each deploy
The invalidation token is used to determine if the cache should be invalidated. If the token is the same as the previous deployment, the cache will not be invalidated.
invalidation.wait?
Type Input
<
boolean
>
Default false
Configure if sst deploy
should wait for the CloudFront cache invalidation to finish.
Waiting for this process to finish ensures that new content will be available after the deploy finishes. However, this process can sometimes take more than 5 mins.
routes
Type Input
<
Record
<
string
, Input
<
string
|
Object
>
>
>
-
edge?
Object
A map of routes to their destinations. The key is the route path and the
value is the destination URL. All routes need to start with /
.
When router receives a request, the requested path is compared with path patterns in the order they are listed. The first match determines which URL the request is routed to.
The /*
route is a default route, meaning that if no routes match, the /*
route will be used. It does not matter where the /*
route is listed in the routes object.
Suppose you have the following three routes.
A request to /api/sample.xml
will match /api/*
first and route to it; even though it matches /*.xml
.
However for this case, a request to /api/users
will route to /api/*
even though it comes after /*
. This is because the /*
route is the default route.
Customize the route behavior with CloudFront Functions.
routes[].edge?
Type Object
Configure CloudFront Functions to customize the behavior of HTTP requests and responses at the edge locations.
routes[].edge.viewerRequest?
Type Input
<
string
>
Default Uses the default viewer request function.
The ARN of the CloudFront function to use for the viewer request.
The viewer request function can be used to modify incoming requests before they reach your origin server. For example, you can redirect users, rewrite URLs, or add headers.
By default, a view request function is created to add the x-forwarded-host
header to the request.
routes[].edge.viewerResponse?
Type Input
<
string
>
Default No viewer response function is set.
The ARN of the CloudFront function to use for the viewer response.
The viewer response function can be used to modify outgoing responses before they reach the viewer. For example, you can add headers, cache control, or rewrite URLs.
routes[].url
Type Input
<
string
>
The destination URL.
transform?
Type Object
Transform how this component creates its underlying resources.
transform.cachePolicy?
Type CachePolicyArgs
|
(
args
:
CachePolicyArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the Cache Policy that’s attached to each CloudFront behavior.
transform.cdn?
Type CdnArgs
|
(
args
:
CdnArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the CloudFront CDN resource.
Properties
nodes
nodes.cdn
Type Cdn
The Amazon CloudFront CDN resource.
url
Type Output
<
string
>
The URL of the Router.
If the domain
is set, this is the URL with the custom domain.
Otherwise, it’s the autogenerated CloudFront URL.
SDK
Use the SDK in your runtime to interact with your infrastructure.
Links
This is accessible through the Resource
object in the SDK.
-
url
string
The URL of the Router.
If the
domain
is set, this is the URL with the custom domain. Otherwise, it’s the autogenerated CloudFront URL.