Skip to content

Router

Reference doc for the `sst.aws.Router` component.

The Router component lets you use a CloudFront distribution to route requests to different parts of your app.

You can use this the routes to route to function URLs, other domains, or any component that has a URL.

Minimal example

new sst.aws.Router("MyRouter", {
routes: {
"/*": "some-internal-service.com"
}
});

Route to a function URL

const myFunction = new sst.aws.Function("MyFunction", {
handler: "src/api.handler",
url: true,
});
new sst.aws.Router("MyRouter", {
routes: {
"/*": myFunction.url
}
});

Route all API requests separately

new sst.aws.Router("MyRouter", {
routes: {
"/*": "myapp.com",
"/api/*": myFunction.url
}
});

Add a custom domain

new sst.aws.Router("MyRouter", {
domain: "myapp.com",
routes: {
"/*": myFunction.url
}
});

Constructor

new Router(name, args, opts?)

Parameters

Properties

nodes

Type Object

The underlying resources this component creates.

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.

The following are accessible through the SDK at runtime.

url

Type 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.

RouterArgs

domain?

Type Input<string | Object>

Set a custom domain for your Router. Supports domains hosted either on Route 53 or outside AWS.

{
domain: "domain.com"
}

Specify a www. version of the custom domain.

{
domain: {
name: "domain.com",
redirects: ["www.domain.com"]
}
}

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: {
name: "app1.domain.com",
aliases: ["app2.domain.com"]
}
}

domain.cert?

Type Input<string>

The ARN of an existing certificate in the us-east-1 region in AWS Certificate Manager to use for the domain. By default, SST will create a certificate with the domain name. The certificate will be created in the us-east-1(N. Virginia) region as required by AWS CloudFront.

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

domain.dns?

Type Input<false | sst.aws.dns | sst.cloudflare.dns | sst.vercel.dns>

Default sst.aws.dns

The DNS adapter you want to use for managing DNS records.

Specify the hosted zone ID for the domain.

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

Domain is hosted on Cloudflare.

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

domain.name

Type Input<string>

The custom domain you want to use. Supports domains hosted on Route 53 or outside AWS.

{
domain: "domain.com"
}

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.

{
domain: {
name: "domain.com",
redirects: ["www.domain.com"]
}
}

routes

Type Input<Record<string, Input<string>>>

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.

{
routes: {
"/api/*.json": "example1.com",
"/api/*": "example2.com",
"/*.xml": "example3.com",
}

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.

{
routes: {
"/*": "myapp.com",
"/api/*": myFunction.url
}
}

transform?

Type Object

Transform how this component creates its underlying resources.

transform.cachePolicy?

Type CachePolicyArgs | (args: CachePolicyArgs => CachePolicyArgs | void)

Transform the Cache Policy that’s attached to each CloudFront behavior.

transform.cdn?

Type CdnArgs | (args: CdnArgs => CdnArgs | void)

Transform the CloudFront CDN resource.