Skip to main content

Architecture

SST provides all the basic building blocks you need to create a full-stack serverless application. An SST app is roughly made up of:

  1. Code that defines your infrastructure.
  2. Code that powers your Lambda functions, or your application code.

Let's look at the two in detail.

Infrastructure

The Infrastructure of your SST app is defined using AWS CDK. It allows you to use real programming languages to define your infrastructure. SST currently supports JavaScript and TypeScript for your infrastructure code.

The infrastructure portion of an SST app is made up of the following.

Constructs

Constructs are the basic building blocks of SST apps. Each construct consists of multiple AWS resources to make up a functional unit. SST picks sensible defaults for the underlying resources, so you are not exposed to all the complexity up front.

For example, Api is a commonly used construct to create a RESTful backend API. It consists of an AWS API Gateway project, Lambda functions, and a few other AWS resources. But it's wrapped up with sensible defaults to help you get started.

new Api(this, "Api", {
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
},
});

You can read more about SST's Progressive disclosure design.

Stacks

Stacks are a way to organize your constructs. There is no universal way to do this however you should try to opt for granular stacks. This is because cloudformation can be slow and the fewer resources there are in a stack, the less complexity there is during deployment.

For example, if you are building a Twitter clone, you might have:

  • A api stack with the API
  • A database stack with the DynamoDB Table
  • A web stack with a React web app for the frontend
  • A digest stack with a Cron job that sends people daily email digest

A quick note on moving constructs across stacks. Once your app has been deployed, moving a construct between stacks requires destroying the construct from the old stack, and recreating it in the new stack. In the case of a Table or Bucket construct, the data is lost. And in the case of an Api, the API endpoint will change when it's recreated.

Apps

An app consists of one or more stacks. In most cases, all of your stacks should be deployed in a single app.

stacks/index.js
export default function main(app) {
app
.stack(CoreStack)
.stack(WebStack)
.stack(DigestStack)
}

Stages

A stage is an environment that the app is deployed to. Typically you should work in a development environment that is an independent clone of your production environment. This allows you to test and ensure that the version of code you are about to deploy is good to go.

By default, the stacks in a CDK app can be deployed to multiple AWS accounts and regions. This doesn't work well when trying to support a separate development environment. Like the one sst start creates.

To fix this, SST has a notion of stages. An SST app can be deployed separately to multiple environments (or stages). A stage is simply a string to distinguish one environment from another.

So if you want to deploy to a stage called prod:

npx sst deploy --stage prod

Behind the scenes, SST uses the name of the app and stage to prefix the resources in the app. This ensures that if an app is deployed to two different stages in the same AWS account, the resource names will not clash. You can also prefix resource names in your stacks by calling the logicalPrefixedName method in sst.App.

this.node.root.logicalPrefixedName("MyResource"); // "dev-my-sst-app-MyResource"

Functions

Some SST constructs use Lambda functions. For example, each route in an Api construct is a Lambda function. This represents your application code. Your function code can be in JavaScript, TypeScript, Python, Golang, and C#.

A JavaScript or TypeScript Lambda function in SST is usually defined using the following format:

"path/to/file.functionName"

Where functionName is the function exported by the given file.

SST is designed to have both the infrastructure code and function code sit in the same repo. You can read more about SST's Project layout.

Deployed to your AWS account

Your SST app is deployed to your AWS account. Make sure to set up the IAM credentials that SST will use to deploy your app.

CDK and CloudFormation

Under the hood, SST uses AWS CDK to compile each stack into a CloudFormation template, and deployed as a CloudFormation stack.