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.

To use SST you'll need:

Getting started​

Create a new project using.

# With npm 6+
npm init sst
# Or with Yarn 0.25+
yarn create sst

Language support​

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

LanguageCDKLambda
JavaScriptβœ“βœ“
TypeScriptβœ“βœ“
GoComing soonβœ“
PythonComing soonβœ“
C#Coming soonβœ“
F#Coming soonβœ“

Project layout​

Your app starts out with the following structure.

my-sst-app
β”œβ”€β”€ README.md
β”œβ”€β”€ node_modules
β”œβ”€β”€ .gitignore
β”œβ”€β”€ package.json
β”œβ”€β”€ sst.json
β”œβ”€β”€ stacks
| β”œβ”€β”€ MyStack.ts
| └── index.ts
└── backend
└── functions
└── lambda.ts

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.

  • backend/ β€” App Code

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

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

Infrastructure​

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

stacks/index.ts
import { MyStack } from "./MyStack";
import { App } from "@serverless-stack/resources";

export default function (app: App) {
app.setDefaultFunctionProps({
runtime: "nodejs14.x",
srcPath: "backend",
bundle: {
format: "esm",
},
});
app.stack(MyStack);
}

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 { StackContext, Api } from "@serverless-stack/resources";

export function MyStack({ stack }: StackContext) {
new Api(stack, "api", {
routes: {
"GET /": "functions/lambda.handler",
},
});
}

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.

backend/functions/lambda.ts
import { APIGatewayProxyHandlerV2 } from "aws-lambda";

export const handler: APIGatewayProxyHandlerV2 = async (event) => {
return {
statusCode: 200,
headers: { "Content-Type": "text/plain" },
body: `Hello, World! Your request was received at ${event.requestContext.time}.`,
};
};

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",
"main": "stacks/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.

  • 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.ts
app.stage; // "dev"
app.region; // "us-east-1"
app.name; // "my-sst-app"

You can also access them in your stacks.

stacks/MyStack.ts
export function MyStack({ app }: StackContext) {
app.stage; // "dev"
app.region; // "us-east-1"
app.name; // "my-sst-app"
}

Building your app​

Once you are ready to build your app and convert your CDK code to CloudFormation, run the following from your project root.

# With npm
npm run build
# Or with Yarn
yarn sst build

This will compile your ES (or TS) code to the .build/ directory in your app. And the synthesized CloudFormation templates are outputted to .build/cdk.out/. Note that, you shouldn't commit the .build/ directory to source control and it's ignored by default in your project's .gitignore.

Deploying an app​

Once your app has been built and tested successfully, you are ready to deploy it to AWS.

# With npm
npm run deploy
# Or with Yarn
yarn deploy

This command uses your default AWS Profile and the region and stage specified in your sst.json.

Or if you want to deploy to a different stage.

npx sst deploy --stage prod

And if your prod environment is in a different AWS account or region, you can do:

AWS_PROFILE=my-profile npx sst deploy --stage prod --region eu-west-1
note

If you are using npm run deploy, you'll need to add an extra -- for the options.

For example, to set the stage and region:

npx sst deploy --stage prod --region eu-west-1

Removing an app​

Finally, you can remove all your stacks and their resources from AWS using.

# With npm
npm run remove
# Or with Yarn
yarn remove

Or if you've deployed to a different stage.

npm run remove --stage prod

Note that this command permanently removes your resources from AWS. It also removes the stack that's created as a part of the debugger.