Config

The sst.config.ts file is used to configure your SST app and its resources.

$config(input: Config): Config

You specify it using the $config function. This takes an object of type Config.

sst.config.ts

/// <reference path="./.sst/platform/config.d.ts" />

export default $config({
  // Your app's config
  app(input) {
    return {
      name: "my-sst-app",
      home: "aws"
    };
  },
  // Your app's resources
  async run() {
    new sst.aws.Bucket("MyBucket");
  }
});

The Config object takes two functions:

1. app — Your config
2. run — Your resources

The app function is evaluated right when your app loads. It’s used to define the app config and its providers.

Note

You need TypeScript 5 to see the types in your config.

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.

Tip

The Global library can help you with your app config and resources.

The run function also has access to a list of Global $ variables and functions. These serve as the context for your app config.

Caution

Do not import the provider packages in your sst.config.ts.

Since SST manages importing your provider packages, it’s recommended not to add any imports in your sst.config.ts.

---

Config

console?

Type Object

• autodeploy Object

  • target

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.

Note

You need to configure an environment in the Console to be able to auto-deploy to it.

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(event) {
      if (
        event.type === "branch" &&
        event.branch === "main" &&
        event.action === "pushed"
       ) {
        return {
          stage: "production",
          runner: { engine: "codebuild", compute: "large" }
        };
      }
    }
  }
}

console.autodeploy.target

target(input)

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.

Note

Git push events for branches, pull requests, and tags are currently supported.

By default, this is what the target function looks like:

target(event) {
  if (event.type === "branch" && event.action === "pushed") {
    return {
      stage: event.branch
        .replace(/[^a-zA-Z0-9-]/g, "-")
        .replace(/-+/g, "-")
        .replace(/^-/g, "")
        .replace(/-$/g, "")
    };
  }

  if (event.type === "pull_request") {
    return { stage: `pr-${event.number}` };
  }
}

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.

Tip

Use the git event to configure how your app will be auto-deployed.

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.

target(event) {
  if (event.type === "branch" && event.branch === "main" && event.action === "pushed") {
    return { stage: "production" };
  }
}

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.

target(event) {
  if (event.type === "branch" && event.branch === "staging") return;
  if (event.type === "branch" && event.branch === "main" && event.action === "pushed") {
    return { stage: "production" };
  }
}

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.

Note

If a target is not returned, the app will not be deployed.

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.

target(event) {
  if (event.type === "branch" && event.branch === "main" && event.action === "pushed") {
    return {
      stage: "production"
      runner: {
        engine: "codebuild",
        compute: "large"
      };
    };
  }
}

app

app(input)

Parameters

• input AppInput

Returns App

The config for your app. It needs to return an object of type App.

Tip

The app function is evaluated when your app loads.

app(input) {
  return {
    name: "my-sst-app",
    home: "aws",
    providers: {
      aws: true,
      cloudflare: {
        accountId: "6fef9ed9089bb15de3e4198618385de2"
      }
    },
    removal: input.stage === "production" ? "retain" : "remove"
  };
},

run

run()

Returns Promise<void | Record<string, any>>

An async function that lets you define the resources in your app.

Note

You can use SST and Pulumi components only in the run function.

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.

async run() {
  const bucket = new sst.aws.Bucket("MyBucket");

  return {
    bucket: bucket.name
  };
}

This will display the following in the CLI.

bucket: bucket-jOaikGu4rla

App

home

Type “aws” | “cloudflare”

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.

Tip

SST uses the home provider to store the state for your app.

Currently supports AWS and Cloudflare.

Setting the home provider is the same as setting the providers list. So if you set home to aws, it’s the same as doing:

{
  home: "aws",
  providers: {
    aws: true
  }
}

If you want to configure your home provider, you can:

{
  home: "aws",
  providers: {
    aws: {
      region: "us-west-2"
    }
  }
}

name

Type string

The name of the app. This is used to prefix the names of the resources in your app.

Caution

If you change the name of your app, it’ll redeploy your app with new resources. The old resources will be orphaned.

This means that you don’t want to change the name of your app without removing the old resources first.

{
  name: "my-sst-app"
}

providers?

Type Record<string, any>

Default The home provider.

The providers that are being used in this app. This allows you to use the components from these providers in your app. Check out the full list in the Directory.

Note

By default, your home provider is included in the providers list.

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:

{
  home: "aws",
  providers: {
    aws: true
  }
}

You can also configure the provider props. Here’s the config for some common providers:

• AWS
• Cloudflare

For example, to change the region for AWS.

{
  providers: {
    aws: {
      region: "us-west-2"
    }
  }
}

You also add multiple providers.

{
  providers: {
    aws: true,
    cloudflare: true
  }
}

By default, we use the latest version of a provider. But you can optionally specify a version.

{
  providers: {
    aws: {
      version: "6.27.0"
    }
  }
}

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.

Tip

It’s a good idea to use retain for your production stage.

Retain resources if it’s the production stage, otherwise remove all resources.

{
  removal: input.stage === "production" ? "retain" : "remove"
}

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.

Tip

Useful in CI where you don’t want it to automatically deploy with a new version of SST.

Takes a specific version.

version: "0.0.300"

Also supports semver ranges.

version: ">= 0.0.300"

AppInput

stage

Type string

The stage this app is running on. This is a string that can be passed in through the CLI.

Caution

Changing the stage will redeploy your app to a new stage with new resources. The old resources will still be around in the old stage.

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:

{
  type: "branch",
  action: "pushed",
  repo: {
    id: 1296269,
    owner: "octocat",
    repo: "Hello-World"
  },
  branch: "main",
  commit: {
    id: "b7e7c4c559e0e5b4bc6f8d98e0e5e5e5e5e5e5e5",
    message: "Update the README with new information"
  },
  sender: {
    id: 1,
    username: "octocat"
  }
}

action

Type “pushed” | “removed”

The type of the git action.

• pushed is when you git push to a branch
• removed is when a branch is removed

branch

Type string

The name of the branch the event is coming from.

commit

Type Object

• id

• message

Info about the commit in the event. This might look like:

{
  id: "b7e7c4c559e0e5b4bc6f8d98e0e5e5e5e5e5e5e5",
  message: "Update the README with new information"
}

commit.id

Type string

The ID of the commit.

commit.message

Type string

The commit message.

repo

Type Object

• id

• owner

• repo

The Git repository the event is coming from. This might look like:

{
  id: 1296269,
  owner: "octocat",
  repo: "Hello-World"
}

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

Type Object

• id

• username

The user that generated the event. For example:

{
  id: 1,
  username: "octocat"
}

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 exampple:

{
  type: "pull_request",
  action: "pushed",
  repo: {
    id: 1296269,
    owner: "octocat",
    repo: "Hello-World"
  },
  number: 1347,
  base: "main",
  head: "feature",
  commit: {
    id: "b7e7c4c559e0e5b4bc6f8d98e0e5e5e5e5e5e5e5",
    message: "Update the README with new information"
  },
  sender: {
    id: 1,
    username: "octocat"
  }
}

action

Type “pushed” | “removed”

The type of the git action.

• pushed is when you git push to the base branch of the PR
• removed 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

Type Object

• id

• message

Info about the commit in the event. This might look like:

{
  id: "b7e7c4c559e0e5b4bc6f8d98e0e5e5e5e5e5e5e5",
  message: "Update the README with new information"
}

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

Type Object

• id

• owner

• repo

The Git repository the event is coming from. This might look like:

{
  id: 1296269,
  owner: "octocat",
  repo: "Hello-World"
}

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

Type Object

• id

• username

The user that generated the event. For example:

{
  id: 1,
  username: "octocat"
}

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:

{
  type: "tag",
  action: "pushed",
  repo: {
    id: 1296269,
    owner: "octocat",
    repo: "Hello-World"
  },
  tag: "v1.5.2",
  commit: {
    id: "b7e7c4c559e0e5b4bc6f8d98e0e5e5e5e5e5e5e5",
    message: "Update the README with new information"
  },
  sender: {
    id: 1,
    username: "octocat"
  }
}

action

Type “pushed” | “removed”

The type of the git action.

• pushed is when you create a tag
• removed is when a tag is removed

commit

Type Object

• id

• message

Info about the commit in the event. This might look like:

{
  id: "b7e7c4c559e0e5b4bc6f8d98e0e5e5e5e5e5e5e5",
  message: "Update the README with new information"
}

commit.id

Type string

The ID of the commit.

commit.message

Type string

The commit message.

repo

Type Object

• id

• owner

• repo

The Git repository the event is coming from. This might look like:

{
  id: 1296269,
  owner: "octocat",
  repo: "Hello-World"
}

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

Type Object

• id

• username

The user that generated the event. For example:

{
  id: 1,
  username: "octocat"
}

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

• architecture?

• compute?

• engine

• timeout?

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:

{
  engine: "codebuild",
  architecture: "x86_64",
  compute: "small",
  timeout: "1 hour"
}

Note

Runners are shared across all apps in the same account and region.

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.

Note

A runner can run multiple builds concurrently.

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 vCPUs
• medium: 7 GB, 4 vCPUs
• large: 15 GB, 8 vCPUs
• xlarge: 30 GB, 16 vCPUs

For arm64 architecture, only small and large are supported:

• small: 4 GB, 2 vCPUs
• large: 8 GB, 4 vCPUs

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. CodeBuild supports a timeout of up to 8 hours.

stage

Type string

The stage the app will be deployed to.