App
The App construct extends cdk.App and is used internally by SST to:
- Automatically prefix stack names with the stage and app name
- Deploy the entire app using the same AWS profile and region
It is made available as the app
in the stacks()
callback in sst.config.ts
of your SST app.
export default {
config(input) {
return {
name: "myapp",
region: "us-east-1",
};
},
stacks(app) {},
} satisfies SSTConfig;
Since it is initialized internally, the props that are passed to App cannot be changed.
Examples
Accessing app properties
The properties of the app can be accessed in the sst.config.ts
as:
stacks(app) {
app.name;
app.stage;
app.region;
app.account;
}
Specifying 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.
stacks(app) {
app.setDefaultFunctionProps({
timeout: 20,
memorySize: 512,
runtime: "go1.x",
environment: { TABLE_NAME: "NOTES_TABLE" },
});
// Start adding stacks
}
Or if you need to access the Stack
scope, you can pass in a callback.
import { StringParameter } from "aws-cdk-lib/aws-ssm";
stacks(app) {
app.setDefaultFunctionProps((stack) => ({
timeout: 20,
memorySize: 512,
runtime: "go1.x",
environment: {
API_KEY: StringParameter.valueFromLookup(stack, "my_api_key"),
},
}));
// Start adding stacks
}
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.
stacks(app) {
app.stack(StackA)
app.addDefaultFunctionEnv({
TABLE_NAME: "NOTES_TABLE"
});
app.addDefaultFunctionPermissions(["s3"]);
app.addDefaultFunctionLayers([mylayer]);
app.stack(StackB)
// Add more stacks
}
So in the above example, the addDefaultFunctionPermissions
and addDefaultFunctionEnv
calls will only impact the functions in StackB
.
You can also use the Stack's setDefaultFunctionProps
to update these for a specific stack.
Setting a default removal policy
You can set a removal policy to apply to all the resources in the app. This is useful for ephemeral environments that need to clean up all their resources on removal.
stacks(app) {
// Remove all resources when the dev stage is removed
if (app.stage === "dev") {
app.setDefaultRemovalPolicy("destroy");
}
// Add stacks
}
Note that, the setDefaultRemovalPolicy
method isn't meant to be used for production environments.
Properties
An instance of App
has the following properties.
account
Type : string
The AWS account the app is being deployed to. This comes from the IAM credentials being used to run the SST CLI.
defaultRemovalPolicy
Type : undefined | "destroy" | "retain" | "snapshot" | "retain-on-update-or-delete"
isActiveStack?
Type : (string) => boolean
local
Type : boolean
Whether or not the app is running locally under
sst dev
mode
Type : "deploy" | "dev" | "remove"
Whether the app is running locally under start, deploy or remove
name
Type : string
The name of your app, comes from the
name
in your
sst.config.ts
region
Type : string
The region the app is being deployed to. If this is not specified as the --region option in the SST CLI, it'll default to the region in your sst.config.ts.
stage
Type : string
The stage the app is being deployed to. If this is not specified as the --stage option, it'll default to the stage configured during the initial run of the SST CLI.
Methods
An instance of App
has the following methods.
addDefaultFunctionBinding
addDefaultFunctionBinding(bind)
Parameters
- bind Array<BindingResource>
Binds additional default resources to be applied to all Lambda functions in the app.
app.addDefaultFunctionBinding([STRIPE_KEY, bucket]);
addDefaultFunctionEnv
addDefaultFunctionEnv(environment)
Parameters
- environment Record<string, string>
Adds additional default environment variables to be applied to all Lambda functions in the app.
app.addDefaultFunctionEnv({
"MY_ENV_VAR": "my-value"
})
addDefaultFunctionLayers
addDefaultFunctionLayers(layers)
Parameters
- layers Array<ILayerVersion>
Adds additional default layers to be applied to all Lambda functions in the stack.
addDefaultFunctionPermissions
addDefaultFunctionPermissions(permissions)
Parameters
- permissions Permissions
Adds additional default Permissions to be applied to all Lambda functions in the app.
app.addDefaultFunctionPermissions(["s3"])
finish
finish()
logicalPrefixedName
logicalPrefixedName(logicalName)
Parameters
- logicalName string
Use this method to prefix resource names in your stacks to make sure they don't thrash when deployed to different stages in the same AWS account. This method will prefix a given resource name with the stage and app name. Using the format
${stage}-${name}-${logicalName}
.
console.log(app.logicalPrefixedName("myTopic"));
// dev-my-app-myTopic
registerTypes
registerTypes(c)
Parameters
- c SSTConstruct
setDefaultFunctionProps
setDefaultFunctionProps(props)
Parameters
- props FunctionProps | (Stack) => FunctionProps
The default function props to be applied to all the Lambda functions in the app. These default values will be overridden if a Function sets its own props. This needs to be called before a stack with any functions have been added to the app.
app.setDefaultFunctionProps({
runtime: "nodejs20.x",
timeout: 30
})
setDefaultRemovalPolicy
setDefaultRemovalPolicy(policy)
Parameters
- policy "destroy" | "retain" | "snapshot" | "retain-on-update-or-delete"
The default removal policy that'll be applied to all the resources in the app. This can be useful to set ephemeral (dev or feature branch) environments to remove all the resources on deletion.
danger
Make sure to not set the default removal policy to
DESTROY
for production environments.
app.setDefaultRemovalPolicy(app.mode === "dev" ? "destroy" : "retain")