Router

The Router component lets you use a CloudFront distribution to direct requests to various parts of your application like:

A URL
A function
A frontend
An S3 bucket

Minimal example

new sst.aws.Router("MyRouter");

Add a custom domain

new sst.aws.Router("MyRouter", {
  domain: "myapp.com"
});

const router = $app.stage === "production"
  ? new sst.aws.Router("MyRouter", {
      domain: {
        name: "example.com",
        aliases: ["*.example.com"]
      }
    })
  : sst.aws.Router.get("MyRouter", "E1XWRGCYGTFB7Z");

Route to a URL

const router = new sst.aws.Router("MyRouter");

router.route("/", "https://some-external-service.com");

Route to an S3 bucket

const myBucket = new sst.aws.Bucket("MyBucket", {
  access: "cloudfront"
});

const router = new sst.aws.Router("MyRouter");
router.routeBucket("/files", myBucket);

You need to allow CloudFront to access the bucket by setting the access prop on the bucket.

Route to a function

const router = new sst.aws.Router("MyRouter", {
  domain: "example.com"
});

const myFunction = new sst.aws.Function("MyFunction", {
  handler: "src/api.handler",
  url: {
    router: {
      instance: router,
      path: "/api"
    }
  }
});

Setting the route through the function, instead of router.route() makes it so that myFunction.url gives you the URL based on the Router domain.

Route to a frontend

const router = new sst.aws.Router("MyRouter");

const mySite = new sst.aws.Nextjs("MyWeb", {
  router: {
    instance: router
  }
});

Setting the route through the site, instead of router.route() makes it so that mySite.url gives you the URL based on the Router domain.

Route to a frontend on a path

const router = new sst.aws.Router("MyRouter");

new sst.aws.Nextjs("MyWeb", {
  router: {
    instance: router,
    path: "/docs"
  }
});

If you are routing to a path, you’ll need to configure the base path in your frontend app as well. Learn more.

Route to a frontend on a subdomain

const router = new sst.aws.Router("MyRouter", {
  domain: {
    name: "example.com",
    aliases: ["*.example.com"]
  }
});

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

We configure *.example.com as an alias so that we can route to a subdomain.

How it works

This uses a CloudFront KeyValueStore to store the routing data and a CloudFront function to route the request. As routes are added, the store is updated.

So when a request comes in, it does a lookup in the store and dynamically sets the origin based on the routing data. For frontends, that have their server functions deployed to multiple regions, it routes to the closest region based on the user’s location.

You might notice a placeholder.sst.dev behavior in CloudFront. This is not used and is only there because CloudFront requires a default behavior.

Limits

There are some limits on this setup but it’s managed by SST.

The CloudFront function can be a maximum of 10KB in size. But because all the route data is stored in the KeyValueStore, the function can be kept small.
Each value in the KeyValueStore needs to be less than 1KB. This component splits the routes into multiple values to keep it under the limit.
The KeyValueStore can be a maximum of 5MB. This is fairly large. But to handle sites that have a lot of files, only top-level assets get individual entries.

Constructor

new Router(name, args?, opts?)

Parameters

name string
args? RouterArgs
opts? ComponentResourceOptions

RouterArgs

domain?

Type Input<string | Object>

aliases?
cert?
dns?
name
redirects?

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.

{
  domain: "example.com"
}

For domains hosted on Cloudflare.

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

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 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 set dns to false.
Add the DNS records in your provider to point to the CloudFront distribution URL.

{
  domain: {
    name: "domain.com",
    dns: false,
    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 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.

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

Use a domain hosted on Cloudflare, needs the Cloudflare provider.

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

Use a domain hosted on Vercel, needs the Vercel provider.

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

domain.name

Type Input<string>

The custom domain you want to use.

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

Can also include subdomains based on the current stage.

{
  domain: {
    name: `${$app.stage}.example.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"]
  }
}

edge?

Type Object

viewerRequest? Input<Object>
- injection
- kvStore?
viewerResponse? Input<Object>
- injection
- kvStore?

Configure CloudFront Functions to customize the behavior of HTTP requests and responses at the edge.

edge.viewerRequest?

Type Input<Object>

Configure the viewer request function.

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.

edge.viewerRequest.injection

Type Input<string>

The code to inject into the viewer request function.

By default, a viewer request function is created to:

Disable CloudFront default URL if custom domain is set.
Add the x-forwarded-host header.
Route requests to the corresponding target based on the domain and request path.

The given code will be injected at the beginning of this function.

async function handler(event) {
  // User injected code

  // Default behavior code

  return event.request;
}

To add a custom header to all requests.

{
  edge: {
    viewerRequest: {
      injection: `event.request.headers["x-foo"] = "bar";`
    }
  }
}

edge.viewerRequest.kvStore?

Type Input<string>

The KeyValueStore to associate with the viewer request function.

{
  edge: {
    viewerRequest: {
      kvStore: "arn:aws:cloudfront::123456789012:key-value-store/my-store"
    }
  }
}

edge.viewerResponse?

Type Input<Object>

Configure the viewer response function.

The viewer response function can be used to modify outgoing responses before they are sent to the client. For example, you can add security headers or change the response status code.

By default, no viewer response function is set. A new function will be created with the provided code.

edge.viewerResponse.injection

Type Input<string>

The code to inject into the viewer response function.

async function handler(event) {
  // User injected code

  return event.response;
}

To add a custom header to all responses.

{
  edge: {
    viewerResponse: {
      injection: `event.response.headers["x-foo"] = "bar";`
    }
  }
}

edge.viewerResponse.kvStore?

Type Input<string>

The KeyValueStore to associate with the viewer response function.

{
  edge: {
    viewerResponse: {
      kvStore: "arn:aws:cloudfront::123456789012:key-value-store/my-store"
    }
  }
}

invalidation?

Type Input<boolean | Object>

paths?
token?
wait?

Default Invalidation is turned off

Configure how the CloudFront cache invalidations are handled.

Setting this to true will invalidate all paths. It’s equivalent to passing in { paths: ["/*"] }.

{
  invalidation: true
}

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.

{
  invalidation: {
    paths: ["/index.html", "/products/*"]
  }
}

This counts as two invalidations.

invalidation.token?

Type Input<string>

Default A unique value is auto-generated on each deploy

A token 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.

You can set this to a hash that’s computed on every deploy. So if the hash changes, the cache will be invalidated.

{
  invalidation: {
    token: "foo123"
  }
}

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.

{
  invalidation: {
    wait: true
  }
}

transform?

Type Object

cachePolicy?
cdn?

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

distributionID

Type Output<string>

The ID of the Router distribution.

nodes

Type Object

cdn

The underlying resources this component creates.

nodes.cdn

Type Output<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 auto-generated CloudFront URL.

SDK

Use the SDK in your runtime to interact with your infrastructure.

Methods

route

route(pattern, url, args?)

Parameters

pattern Input<string>
The path pattern to match for this route.
url Input<string>
The destination URL to route matching requests to.
args? Input<RouterUrlRouteArgs>
Configure the route.

Returns void

Add a route to a destination URL.

You can match a route based on:

A path like /api
A domain pattern like api.example.com
A combined pattern like dev.example.com/api

For example, to match a path.

router.route("/api", "https://api.example.com");

Or match a domain.

router.route("api.myapp.com/", "https://api.example.com");

Or a combined pattern.

router.route("dev.myapp.com/api", "https://api.example.com");

You can also rewrite the request path.

router.route("/api", "https://api.example.com", {
  rewrite: {
    regex: "^/api/(.*)$",
    to: "/$1"
  }
});

Here something like /api/users/profile will be routed to https://api.example.com/users/profile.

routeBucket

routeBucket(pattern, bucket, args?)

Parameters

pattern Input<string>
The path pattern to match for this route.
bucket Input<Bucket>
The S3 bucket to route matching requests to.
args? Input<RouterBucketRouteArgs>
Configure the route.

Returns void

Add a route to an S3 bucket.

Let’s say you have an S3 bucket that gives CloudFront access.

const bucket = new sst.aws.Bucket("MyBucket", {
  access: "cloudfront"
});

You can match a pattern and route to it based on:

A path like /api
A domain pattern like api.example.com
A combined pattern like dev.example.com/api

For example, to match a path.

router.routeBucket("/files", bucket);

Or match a domain.

router.routeBucket("files.example.com", bucket);

Or a combined pattern.

router.routeBucket("dev.example.com/files", bucket);

You can also rewrite the request path.

router.routeBucket("/files", bucket, {
  rewrite: {
    regex: "^/files/(.*)$",
    to: "/$1"
  }
});

Here something like /files/logo.png will be routed to /logo.png.

static get

Router.get(name, distributionID, opts?)

Parameters

name string
The name of the component.
distributionID Input<string>
The ID of the existing Router distribution.
opts? ComponentResourceOptions

Returns Router

Reference an existing Router with the given Router distribution ID.

Let’s say you create a Router in the dev stage. And in your personal stage frank, you want to share the same Router.

const router = $app.stage === "frank"
  ? sst.aws.Router.get("MyRouter", "E2IDLMESRN6V62")
  : new sst.aws.Router("MyRouter");

Here E2IDLMESRN6V62 is the ID of the Router distribution created in the dev stage. You can find this by outputting the distribution ID in the dev stage.

return {
  router: router.distributionID
};

Learn more about how to configure a router for your app.

RouterBucketRouteArgs

connectionAttempts?

Type Input<number>

Default 3

The number of times that CloudFront attempts to connect to the origin. Must be between 1 and 3.

{
  connectionAttempts: 1
}

connectionTimeout?

Type Input<“${number} second” | “${number} seconds”>

Default “10 seconds”

The number of seconds that CloudFront waits before timing out and closing the connection to the origin. Must be between 1 and 10 seconds.

{
  connectionTimeout: "3 seconds"
}

rewrite?

Type Input<Object>

regex
to

Rewrite the request path.

If the route path is /files/* and a request comes in for /files/logo.png, the request path the destination sees is /files/logo.png.

If you want to serve the file from the root of the bucket, you can rewrite the request path to /logo.png.

{
  rewrite: {
    regex: "^/files/(.*)$",
    to: "/$1"
  }
}

rewrite.regex

Type Input<string>

The regex to match the request path.

rewrite.to

Type Input<string>

The replacement for the matched path.

RouterUrlRouteArgs

connectionAttempts?

Type Input<number>

Default 3

The number of times that CloudFront attempts to connect to the origin. Must be between 1 and 3.

{
  connectionAttempts: 1
}

connectionTimeout?

Type Input<“${number} second” | “${number} seconds”>

Default “10 seconds”

The number of seconds that CloudFront waits before timing out and closing the connection to the origin. Must be between 1 and 10 seconds.

{
  connectionTimeout: "3 seconds"
}

keepAliveTimeout?

Type Input<“${number} second” | “${number} seconds”>

Default “5 seconds”

The number of seconds that CloudFront should try to maintain the connection to the destination after receiving the last packet of the response. Must be between 1 and 60 seconds

{
  keepAliveTimeout: "10 seconds"
}

readTimeout?

Type Input<“${number} second” | “${number} seconds”>

Default “20 seconds”

The number of seconds that CloudFront waits for a response after routing a request to the destination. Must be between 1 and 60 seconds.

When compared to the connectionTimeout, this is the total time for the request.

{
  readTimeout: "60 seconds"
}

rewrite?

Type Input<Object>

regex
to

Rewrite the request path.

If the route path is /api/* and a request comes in for /api/users/profile, the request path the destination sees is /api/users/profile.

If you want to serve the route from the root, you can rewrite the request path to /users/profile.

{
  rewrite: {
    regex: "^/api/(.*)$",
    to: "/$1"
  }
}

rewrite.regex

Type Input<string>

The regex to match the request path.

rewrite.to

Type Input<string>

The replacement for the matched path.