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
├── lib
|   ├── MyStack.js
|   └── index.js
└── src
    └── lambda.js

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

lib/ — App Infrastructure
The code that describes the infrastructure of your serverless app is placed in the lib/ 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 lib/index.js file is the entry point for defining the infrastructure of your app. It has a default export function to add your stacks.

lib/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 lib/MyStack.js you can add the resources to your stack.

lib/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",
  "esbuildConfig": "config/esbuild.js"
}

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 lib/index.ts or lib/index.js for TypeScript and JavaScript respectively.
esbuildConfig
SST automatically transpiles your ES (and TypeScript) code using esbuild. The esbuildConfig allows you to configure esbuild.
To use an esbuild plugin install the plugin npm package in your project. Then create a config file that exports the plugin.
config/esbuild.js
const { esbuildDecorators } = require("@anatine/esbuild-decorators");

module.exports = {
plugins: [
esbuildDecorators(),
]
};
note
Only the "plugins" option in the esbuild config is currently supported.
You can reference this config in your sst.json; "esbuildConfig": "config/esbuild.js".

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

lib/index.js

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

You can also access them in your stacks.

JavaScript
TypeScript

lib/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"
  }
}