Skip to content
Ion
Docs Console Examples

Config

Reference doc for the `sst.config.ts`.

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({
  app(input) {
    return {
      name: "my-sst-app",
      home: "aws"
    };
  },
  async run() {
    new sst.aws.Bucket("MyBucket");
  }
});

The Config object takes two functions: app and run.

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

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.

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.

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.

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. SST supports all Pulumi’s providers. This allows you to use the components from these providers in your app.

For example, if you use the AWS Classic provider, you can use the aws components in your app.

import * as aws from "@pulumi/aws";


new aws.s3.BucketV2("b", {
  bucket: "mybucket"
});

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:

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.

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

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

version?

Type string

Optional required version for sst.

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.

If not passed in, it’ll use the username of your local machine, or prompt you for it.

Config

app

app(input)

Parameters

Returns App

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

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.

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