Skip to main content

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

Language support

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

LanguageCDKLambda
JavaScriptβœ“βœ“
TypeScriptβœ“βœ“
GoComing soonβœ“
PythonComing 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.

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