Skip to main content

Stack

caution

This is the SST v0.x Constructs doc. SST v1 is now released. If you are using v1, see the v1 Constructs doc. If you are looking to upgrade to v1, check out the migration steps.

The Stack construct extends cdk.Stack. It automatically prefixes the stack names with the stage and app name to ensure that they can be deployed to multiple regions in the same AWS account. It also ensure that the stack uses the same AWS profile and region as the app.

Initializer​

new Stack(scope: Construct, id: string, props: StackProps)

Parameters

Examples​

Creating a new stack​

Create a new stack by adding this in stacks/MyStack.js.

import { Stack } from "@serverless-stack/resources";

export default class MyStack extends Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    // Define your stack
  }
}

Adding to an app​

Add it to your app in stacks/index.js.

import MyStack from "./MyStack";

export default function main(app) {
  // Set default runtime for all functions
  app.setDefaultFunctionProps({
    runtime: "nodejs14.x"
  });

  new MyStack(app, "my-stack");

  // Add more stacks
}

Here app is an instance of App.

Note that, setting the env for an individual stack is not allowed.

new MyStack(app, "my-stack", { env: { account: "1234", region: "us-east-1" } });

It will throw this error.

Error: Do not directly set the environment for a stack

This is by design. The stacks in SST are meant to be re-deployed for multiple stages (like Serverless Framework). And so they depend on the region and AWS profile that's passed in through the CLI. If a stack is hardcoded to be deployed to a specific account or region, it can break your deployment pipeline.

Accessing app properties​

The stage, region, and app name can be accessed through the app object. In your stacks (for example, stacks/MyStack.ts) you can use.

export function MyStack({ app }: StackContext) {
  app.stage;
  app.region;
  app.name;
}

You can use this to conditionally add stacks or resources to your app.

Specifying default function props​

You can set some function props and have them apply to all the functions in a stack. This must be called before any functions have been added to the stack; so that all functions will be created with these defaults.

function MyStack({ stack }) {
  stack.setDefaultFunctionProps({
    timeout: 20,
    memorySize: 512,
    runtime: "go1.x",
    environment: { TABLE_NAME: "NOTES_TABLE" },
  });
  // Start adding resources
}

It'll also override any props set by the App's setDefaultFunctionProps, while merging the environment and permission props.

Updating default function props​

You can also use addDefaultFunctionPermissions, addDefaultFunctionEnv, and addDefaultFunctionLayers to progressively add more permissions, environment variables, and layers to the defaults. These can be called multiple times and from anywhere.

However, they only affect the functions that are created after the call.

function MyStack({ stack }) {
  new Api(stack, "Api1", {
    routes: {
      "GET /": "src/hello.main",
    },
  });

  stack.addDefaultFunctionEnv({
    TABLE_NAME: "NOTES_TABLE"
  });

  stack.addDefaultFunctionPermissions(["s3"]);

  stack.addDefaultFunctionLayers([mylayer]);

  new Api(stack, "Api2", {
    routes: {
      "GET /": "src/world.main",
    },
  });
}

So in the above example, the addDefaultFunctionPermissions and addDefaultFunctionEnv calls will only impact the functions in Api2.

Prefixing resource names​

You can optionally prefix resource names to make sure they don't thrash when deployed to different stages in the same AWS account.

You can do so in your stacks.

scope.logicalPrefixedName("MyResource"); // Returns "dev-my-sst-app-MyResource"

This invokes the logicalPrefixedName method in App that your stack is added to. This'll return dev-my-sst-app-MyResource, where dev is the current stage and my-sst-app is the name of the app.

Adding stack outputs​

function MyStack({ stack }) {
  const topic = new Topic(stack, "Topic");
  const queue = new Queue(stack, "Queue");

  stack.addOutputs({
    TopicArn: topic.snsTopic.topicArn,
    QueueArn: topic.sqsQueue.queueArn,
  });
}

Adding stack exports​

function MyStack({ stack }) {
  const topic = new Topic(stack, "Topic");

  stack.addOutputs({
    TopicArn: { value: topic.snsTopic.topicArn, exportName: "MyTopicArn" },
  });
}

Accessing AWS account info​

To access the AWS account and region your app is being deployed to, use the following in your Stack instances.

this.region;
this.account;

The region here is the same as the one you can find in the scope instance in the constructor.

Methods​

An instance of Stack contains the following methods.

getAllFunctions​

getAllFunctions(): Function

Returns

Returns all the Function instances in this stack.

setDefaultFunctionProps​

setDefaultFunctionProps(props: FunctionProps)

Parameters

  • props FunctionProps

The default function props to be applied to all the Lambda functions in the stack. These default values will be overridden if a Function sets its own props. This cannot be called after any functions have been added to the stack.

note

The setDefaultFunctionProps function must be called before any functions have been added.

Takes the FunctionProps.

This overrides the props from the App's setDefaultFunctionProps, while merging the permissions and environment props.

addDefaultFunctionEnv​

addDefaultFunctionEnv(env: { [key: string]: string })

Parameters

  • env { [key: string]: string }

Adds additional default environment variables to be applied to all Lambda functions in the stack.

note

Only functions created after a addDefaultFunctionEnv call will contain the new values.

addDefaultFunctionPermissions​

addDefaultFunctionPermissions(permissions: Permissions)

Parameters

  • permissions Permissions

Adds additional default Permissions to be applied to all Lambda functions in the stack.

note

Only functions created after a addDefaultFunctionPermissions call will contain the new values.

addDefaultFunctionLayers​

addDefaultFunctionLayers(layers: lambda.ILayerVersion[])

Parameters

Adds additional default layers to be applied to all Lambda functions in the stack.

note

Only functions created after a addDefaultFunctionLayers call will contain the new values.

addOutputs​

addOutputs(outputs: { [key: string]: string | cdk.CfnOutputProps })

Parameters

  • outputs { [key: string]: string | cdk.CfnOutputProps }

An associative array with the key being the output name as a string and the value is either a string as the output value or the cdk.CfnOutputProps.

StackProps​

Extends cdk.StackProps.