import config from "../config";

SST is a collection of <a href={ ${ config.github }/tree/master/packages }>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.

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

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

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.

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.

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.

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.

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",
  },
});

The above API endpoint invokes the handler function in 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.

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

{
  "name": "my-sst-app",
  "stage": "dev",
  "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.

• stage and region

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

• 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.

  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.

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

You can also access them in your stacks.

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