Installation

SST is a collection of npm packages.

Requirements#

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

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",
"stage": "dev",
"region": "us-east-1",
"lint": true
}

The stage and the region are defaults for your app and can be overridden using the --stage and --region options. The name is used while prefixing your stack and resource names.

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

You'll be able to access the stage, region, and name of your app in lib/index.js.

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

You can also access them in your stacks, 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"
}
}

And in TypeScript.

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

You can read more about the additional set of constructs that SST provides here.

Edit this page