Skip to main content

DebugStack

caution

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

The DebugStack construct is used internally to create the resources needed to power Live Lambda Development. Note that, the DebugStack construct should only be created inside the DebugApp.

It 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 ensures that the stack uses the same AWS profile and region as the app.

Examples​

Adding to an app​

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

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

export function debugApp(app) {
  new DebugStack(app, "debug-stack");

  // Customize debug stack
}

Here app is an instance of DebugApp.

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

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

It will throw an 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 to multiple stages. 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/index.js you can use.

export function debugApp(app) {
  new DebugStack(app, "debug-stack");

  app.stage;
  app.region;
  app.name;
}

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

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 DebugApp that the DebugStack is added to. This'll return dev-my-sst-app-debug-stack, where dev is the current stage and my-sst-app is the name of the app.

Customizing stack name​

export function debugApp(app) {
  new DebugStack(app, "debug-stack", {
    stackName: app.logicalPrefixedName("my-debug-stack"),
  });
}

Configuring the DynamoDB table​

Configure the internally created CDK Table instance.

export function debugApp(app) {
  new DebugStack(app, "debug-stack", {
    cdk: {
      table: {
        pointInTimeRecovery: true,
      }
    }
  });
}

Using existing resources​

export function debugApp(app) {
  new DebugStack(app, "debug-stack", {
    payloadBucketArn: "arn:aws:s3:::my-bucket",
    websocketHandlerRoleArn: "arn:aws:iam::123456789012:role/my-role",
  });
}

Tagging the debug stack​

import * as cdk from "aws-cdk-lib";

export function debugApp(app) {
  new sst.DebugStack(app, "debug-stack");
  cdk.Tags.of(app).add("my-tag", `${app.stage}-${app.region}`);
}

Constructor​

new DebugStack(scope, id, props)

Parameters

DebugStackProps​

Stack properties for the DebugStack.

payloadBucketArn?​

Type : string

S3 bucket to store large websocket payloads.

websocketHandlerRoleArn?​

Type : string

Lambda function props for WebSocket request handlers.

cdk.table?​

Type : Omit<TableProps, "sortKey" | "partitionKey">

Override the settings of the internally created DynamoDB table

Properties​

An instance of DebugStack has the following properties.

stage​

Type : string