Config
Reference doc for the `sst.config.ts`.
The sst.config.ts
file is used to configure your SST app and its resources.
You specify it using the $config
function. This takes an object of type Config
.
The Config
object takes two functions:
The app
function is evaluated right when your app loads. It’s used to define the app config and its providers.
You can add Pulumi code in the run
function not the app
function. While the run
function is where you define your resources using SST or Pulumi’s components.
The run function also has access to a list of Global $
variables and functions. These serve as the context for your app config.
Since SST manages importing your provider packages, it’s recommended not to add any imports
in your sst.config.ts
.
.env
Your .env
and .env.<stage>
files are loaded as environment variables in your config.
They need to be in the same directory as your sst.config.ts
.
And are available as process.env
in both your app
and run
functions.
The .env
file takes precedence over .env.<stage>
. So if you have a .env
and a
.env.dev
file, the values in the .env
file will be used.
Make sure the stage name in your .env.<stage>
matches the stage your app is running on.
Config
console?
Type Object
-
autodeploy
Object
Configure how your app works with the SST Console. Learn more about Autodeploy.
console.autodeploy
Type Object
Default Auto-deploys branches and PRs.
Auto-deploys your app when you git push to your repo. Uses AWS CodeBuild in your account to run the build.
You are only charged for the number of build minutes that you use. The pricing is based on the machine config used. Learn more about CodeBuild pricing.
By default, this auto-deploys when you git push to a:
- branch: The stage name is a sanitized version of the branch name. When a branch is removed, the stage is not removed.
- pull request: The stage name is
pr-<number>
. When a pull request is closed, the stage is removed.
You can pass in your own target
function to customize this behaviour and the machine
that’ll be used to run the build.
console.autodeploy.target
Parameters
-
input
BranchEvent
|
TagEvent
|
PullRequestEvent
Returns undefined
|
Target
Defines the stage the app will be auto-deployed to.
When a git event is received, Autodeploy will run the target
function with the
git event. This function should return the stage the app will be deployed to.
Or undefined
if the deploy should be skipped.
By default, this is what the target
function looks like:
Here we are sanitizing the branch name to generate the stage name. We are also only deploying when pushed to a branch, and not when a branch is removed.
You can change the default behavior by passing in your own target
function.
For example, to auto-deploy to the production
stage when you git push to the
main
branch.
If you don’t want to auto-deploy for a given event, you can return undefined
. For
example, to skip any deploys to the staging
stage.
The stage that is returned is then compared to the environments set in the app settings in the Console. If the stage matches a deployment target, the stage will be deployed to that environment. If no matching environment is found, the deploy will be skipped.
In addition to the stage
you can also configure the runner
that will run the build.
For example, to use a larger machine for the production
stage.
app
Parameters
-
input
AppInput
Returns App
The config for your app. It needs to return an object of type App
. The app
function is evaluated when your app loads.
Here’s an example of a simple app
function.
run
Returns Promise
<
void
|
Record
<
string
, any
>
>
An async function that lets you define the resources in your app.
You can optionally return an object that’ll be displayed as the output in the CLI.
For example, here we return the name of the bucket we created.
This will display the following in the CLI on sst deploy
and sst dev
.
These outputs are also written to a .sst/output.json
file after every successful deploy.
It contains the above outputs in JSON.
App
home
Type “
aws
”
|
“
cloudflare
”
|
“
local
”
The provider SST will use to store the state for your app. The state keeps track of all your resources and secrets. The state is generated locally and backed up in your cloud provider.
Currently supports AWS, Cloudflare and local.
If you want to configure the aws or cloudflare home provider, you can:
name
Type string
The name of the app. This is used to prefix the names of the resources in your app.
This means that you don’t want to change the name of your app without removing the old resources first.
providers?
Type Record
<
string
, any
>
Default The home
provider.
The providers that are being used in this app. This allows you to use the resources from these providers in your app.
Check out the full list in the Directory.
If you don’t set a provider
it uses your home
provider with the default config. So if you set home
to aws
, it’s the same as doing:
You can also configure the provider props. Here’s the config for some common providers:
For example, to change the region for AWS.
removal?
Type “
remove
”
|
“
retain
”
|
“
retain-all
”
Default “retain”
Configure how your resources are handled on sst remove
:
remove
: Remove all your resources on remove.retain
: Retains S3 buckets and DynamoDB tables, and remove all other resources.retain-all
: Retains all your resources on remove.
Retain resources if it’s the production stage, otherwise remove all resources.
version?
Type string
Default The latest version of SST.
The version of SST supported by the app. The CLI will fail any commands if the version does not match.
Takes a specific version.
Also supports semver ranges.
AppInput
stage
Type string
The stage this app is running on. This is a string that can be passed in through the CLI.
If not passed in, it’ll use the username of your local machine, or prompt you for it.
BranchEvent
A git event for when a branch is updated or deleted. For example:
action
Type “
pushed
”
|
“
removed
”
The type of the git action.
pushed
is when you git push to a branchremoved
is when a branch is removed
branch
Type string
The name of the branch the event is coming from.
commit
commit.id
Type string
The ID of the commit.
commit.message
Type string
The commit message.
repo
repo.id
Type number
The ID of the repo. This is usually a number.
repo.owner
Type string
The name of the owner or org the repo to belongs to.
repo.repo
Type string
The name of the repo.
sender
sender.id
Type number
The ID of the user.
sender.username
Type string
The username of the user.
type
Type “
branch
”
The git event type, for the BranchEvent
it’s branch
.
PullRequestEvent
A git event for when a pull request is updated or deleted. For example:
action
Type “
pushed
”
|
“
removed
”
The type of the git action.
pushed
is when you git push to the base branch of the PRremoved
is when the PR is closed or merged
base
Type string
The base branch of the PR. This is the branch the code is being merged into.
commit
commit.id
Type string
The ID of the commit.
commit.message
Type string
The commit message.
head
Type string
The head branch of the PR. This is the branch the code is coming from.
number
Type number
The pull request number.
repo
repo.id
Type number
The ID of the repo. This is usually a number.
repo.owner
Type string
The name of the owner or org the repo to belongs to.
repo.repo
Type string
The name of the repo.
sender
sender.id
Type number
The ID of the user.
sender.username
Type string
The username of the user.
type
Type “
pull_request
”
The git event type, for the PullRequestEvent
it’s pull_request
.
TagEvent
A git event for when a tag is created or deleted. For example:
action
Type “
pushed
”
|
“
removed
”
The type of the git action.
pushed
is when you create a tagremoved
is when a tag is removed
commit
commit.id
Type string
The ID of the commit.
commit.message
Type string
The commit message.
repo
repo.id
Type number
The ID of the repo. This is usually a number.
repo.owner
Type string
The name of the owner or org the repo to belongs to.
repo.repo
Type string
The name of the repo.
sender
sender.id
Type number
The ID of the user.
sender.username
Type string
The username of the user.
tag
Type string
The name of the tag. For example, v1.5.2
.
type
Type “
tag
”
The git event type, for the TagEvent
it’s tag
.
Target
runner?
Type Object
Configure the runner that will run the build.
It uses this to create a runner — a AWS CodeBuild project and an IAM Role, in your account. By default it uses:
Once a runner is created, it can be used to run multiple builds of the same machine config concurrently.
You are only charged for the number of build minutes that you use. The pricing is based on the machine config used. Learn more about CodeBuild pricing.
If a runner with the given config has been been previously created, it’ll be reused. The Console will also automatically remove runners that have not been used for more than 7 days.
runner.architecture?
Type “
x86_64
”
|
“
arm64
”
Default x86_64
The architecture of the build machine.
runner.compute?
Type “
small
”
|
“
medium
”
|
“
large
”
|
“
xlarge
”
Default small
The compute size of the build environment.
For x86_64
, it can be the following:
small
: 3 GB, 2 vCPUsmedium
: 7 GB, 4 vCPUslarge
: 15 GB, 8 vCPUsxlarge
: 30 GB, 16 vCPUs
For arm64
architecture, only small
and large
are supported:
small
: 4 GB, 2 vCPUslarge
: 8 GB, 4 vCPUs
To increase the memory used by your Node.js process in the build environment, you’ll want
to set the NODE_OPTIONS
environment variable to --max-old-space-size=xyz
. Where xyz
is the memory size in MB. By default, this is set to 1.5 GB.
Read more about the CodeBuild build environments.
runner.engine
Type “
codebuild
”
The service used to run the build. Currently, only AWS CodeBuild is supported.
runner.timeout?
Type “
${number} minute
”
|
“
${number} minutes
”
|
“
${number} hour
”
|
“
${number} hours
”
Default 1 hour
The timeout for the build. It can be from 5 minutes
to 1 hour
.
stage
Type string
The stage the app will be deployed to.