Installation

SST is a collection of npm packages that allow you to create a serverless app.

You can define your apps with a combination of Infrastructure as Code (using CDK) and Lambda functions.

Requirements

• Node.js >= 10.15.1
• An AWS account with the AWS CLI configured locally

Language support

SST supports JavaScript, TypeScript, Python, Golang, C#, and F#.

Language	CDK	Lambda
JavaScript	✓	✓
TypeScript	✓	✓
Go	Coming soon	✓
Python	Coming soon	✓
C#	Coming soon	✓
F#	Coming soon	✓

Getting started

Create a new project using.

npx create-serverless-stack@latest my-sst-app

Or alternatively, with a newer version of npm or Yarn.

# With npm 6+
npm init serverless-stack@latest my-sst-app
# Or with Yarn 0.25+
yarn create serverless-stack my-sst-app

This by default creates a JavaScript/ES project. If you instead want to use TypeScript.

npx create-serverless-stack@latest my-sst-app --language typescript

Or if you want to use Python.

npx create-serverless-stack@latest my-sst-app --language python

Or if you want to use Go.

npx create-serverless-stack@latest my-sst-app --language go

Or if you want to use C#.

npx create-serverless-stack@latest my-sst-app --language csharp

Or if you want to use F#.

npx create-serverless-stack@latest my-sst-app --language fsharp

By default your project is using npm as the package manager, if you'd like to use Yarn.

npx create-serverless-stack@latest my-sst-app --use-yarn

Note that, if you are using npm init, you'll need to add an extra -- before the options.

npm init serverless-stack@latest my-sst-app -- --language typescript

You can read more about the create-serverless-stack CLI here.

Project layout

Your app starts out with the following structure.

my-sst-app
├── README.md
├── node_modules
├── .gitignore
├── package.json
├── sst.json
├── test
│   └── MyStack.test.js
├── stacks
|   ├── MyStack.js
|   └── index.js
└── src
    └── lambda.js

An SST app is made up of a couple of parts.

• stacks/ — App Infrastructure

  The code that describes the infrastructure of your serverless app is placed in the stacks/ directory of your project. SST uses AWS CDK, to create the infrastructure.

• src/ — App Code

  The code that’s run when your app is invoked is placed in the src/ directory of your project. These are your Lambda functions.

• test/ — Unit tests

  There's also a test/ directory where you can add your tests. SST uses Jest internally to run your tests.

You can change this structure around to fit your workflow. This is just a good way to get started.

Infrastructure

The stacks/index.js file is the entry point for defining the infrastructure of your app. It has a default export function to add your stacks.

stacks/index.js

import MyStack from "./MyStack";

export default function main(app) {
  new MyStack(app, "my-stack");

  // Add more stacks
}

You'll notice that we are using import and export. This is because SST automatically transpiles your ES (and TypeScript) code using esbuild.

In the sample stacks/MyStack.js you can add the resources to your stack.

stacks/MyStack.js

import * as sst from "@serverless-stack/resources";

export default class MyStack extends sst.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    // Define your stack
  }
}

Note that the stacks in SST use sst.Stack as opposed to cdk.Stack. This allows us to deploy the same stack to multiple environments.

In the sample app we are using a higher-level API construct to define a simple API endpoint.

const api = new sst.Api(this, "Api", {
  routes: {
    "GET /": "src/lambda.handler",
  },
});

Functions

The above API endpoint invokes the handler function in src/lambda.js.

src/lambda.js

export async function handler() {
  return {
    statusCode: 200,
    body: "Hello World!",
    headers: { "Content-Type": "text/plain" },
  };
}

Notice that we are using export here as well. SST also transpiles your function code.

Project config

Your SST app also includes a config file in sst.json.

sst.json

{
  "name": "my-sst-app",
  "region": "us-east-1",
  "lint": true,
  "typeCheck": true,
  "main": "infra/index.ts"
}

Let's look at these options in detail.

• name

  Used while prefixing your stack and resource names.

• region

  Defaults for your app and can be overridden using the --region CLI option.

• lint

  For JavaScript and TypeScript apps, SST automatically lints your CDK and Lambda function code using ESLint. The lint option allows you to turn this off.

• typeCheck

  For TypeScript apps, SST also automatically type checks your CDK and Lambda function code using tsc. The typeCheck option allows you to turn this off.

• main

  The entry point to your SST app. Defaults to stacks/index.ts or stacks/index.js for TypeScript and JavaScript respectively.

Note that, you can access the stage, region, and name in the entry point of your app.

stacks/index.js

app.stage; // "dev"
app.region; // "us-east-1"
app.name; // "my-sst-app"

You can also access them in your stacks.

JavaScript

stacks/MyStack.js

class MyStack extends sst.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    scope.stage; // "dev"
    scope.region; // "us-east-1"
    scope.name; // "my-sst-app"
  }
}

TypeScript

stacks/MyStack.ts

class MyStack extends sst.Stack {
  constructor(
    scope: sst.App, id: string, props?: sst.StackProps
  ) {
    super(scope, id, props);

    scope.stage; // "dev"
    scope.region; // "us-east-1"
    scope.name; // "my-sst-app"
  }
}