Migrate From v2

Migrate your SST v2 apps to v3.

This guide will help you migrate your SST v2 apps to v3. We look at the major differences between v2 and v3 below. But to get a quick intro, we recommend reading the What is SST and Workflow docs.

We’ll then go over a migration plan that you can use. The exact details of this will be different from team to team depending on the resources in it, and sensitivity of downtime.

Getting help

SST v3 has been around for a few months with a pretty sizeable community on Discord. We’ve created a channel for folks looking to migrate.

Join #migrate-from-v2 on Discord.

Not supported

While the goal with v3 is to support most of what’s in v2, there are a couple of things that haven’t been supported yet. If you rely on these heavily in your app, we recommend waiting a bit longer till we support them.

Construct	GitHub Issue
`Job`	#170
`Auth`	#90
`Script`	#811
`EventBus`	#67
`RDS` MySQL	#812
`Function` non-Node.js runtimes	#366 #640 #179 #1046

Feel free to let us know via the linked GitHub issues if these are blockers for you. It’ll help us prioritize this list.

Major changes

If you are coming from SST v2, it’s worth starting with the big differences between v2 and v3. It’ll help you understand the types of changes you’ll need to make as you migrate.

No CloudFormation

Let’s start with the obvious. SST v3 moves away from CloudFormation and CDK, we’ve written in detail about why we decided to do this.

No CloudFormation, means a couple of things:

There are no stacks, all the resources are defined through the same function in the sst.config.ts.
The outputs of constructs or components are different. These used to be tokens that would get replaced on deploy. Now they are something called Outputs.
The state of your app is stored locally and backed up to S3. Learn more about State.

No CDK

And moving away from CDK means:

You cannot fall back to CDK constructs if something isn’t supported by SST. Instead there is the AWS Classic provider from Pulumi that’s built on Terraform. There are also 150+ other providers that allow you to build on any cloud. Check out the Directory.

If you are using a lot of higher level CDK constructs in your v2 app, it’s going to be really hard to migrate to v3. The Pulumi/Terraform ecosystem is fairly complete but it’s mainly made up of low level resources. You might not have ready replacements for your CDK constructs.
Since the constructs or components are no longer built on CDK; they don’t have a cdk prop. Instead, there’s a transform prop that lets you modify the props that a component sends to its underlying resources. Learn more about the transform prop.

sst.config.ts

The sst.config.ts is similar in v3 but there are some changes. Here’s a comparison of the general structure, we look at this in detail in a section below.

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

export default {
  // Your app's config
  config(_input) {
    return {
      name: "my-sst-app",
      region: "us-east-1"
    };
  },
  // Your app's resources
  stacks(app) { }
} satisfies SSTConfig;

Learn more about the new sst.config.ts.

sst dev

The sst dev CLI has been completely reworked. It now runs a multiplexer that deploys your app and runs your frontends together. So you don’t need to:

Start your frontend separately
Need to wrap your frontend dev script with sst bind

Learn more about sst dev.

sst build

There is no sst build CLI. Instead you can run sst diff to see what changes will be deployed, without doing an actual deploy.

Learn more about sst diff.

Resource binding

Resource binding is now called resource linking, the bind prop is now renamed to link. The Node.js client or JS SDK has been reworked so that all linked resources are now available through the Resource object. We’ll look at this in detail below.

The client handlers and hooks have not been supported yet.

Learn more about Resource linking.

Secrets

Secrets are not stored in SSM. Instead they are encrypted and stored in your state file. It’s encrypted using a passphrase that’s stored in SSM.

Loading secrets in your functions no longer needs a top-level await.

Migration plan

Say you have a v2 app in a git repo that’s currently deployed to production. Here’s how we recommend carrying out the migration.

Use the steps below to migrate over your app to a non-prod stage. You don’t need to import any resources, just recreate them.
Test your non-prod version of your v3 app.
Then for your prod stage, follow the steps below and make the import, domain, and subscriber changes.
Once the prod version of your v3 app is running, clean up some of the v2 prod resources.

The general idea here is to have the v2 app hand over control of the underlying resources to the v3 version of the app.

Setup

Start by setting the removal policy to retain in the v2 app for the production stages. This ensures resources don’t get accidentally removed.
```
app.setDefaultRemovalPolicy("retain");
```
You’ll want to deploy your app once after setting this.
Create a new branch in your repo for the upcoming changes.
For the prod version of the v3 app, pick a different stage name. Say your prod stage in v2 is called production. Maybe use prod, main, or live for your v3 app. Or vice versa. This isn’t strictly necessary, but we recommend doing this because you don’t want to change the wrong resources by mistake.

Init v3

Now let’s set up our new v3 app in the root of your project.

Update SST to v3. Or set the version by hand in your package.json. Make sure to this across all the packages in your repo.
```
npm update sst
```
Ensure v3 is installed.
```
npx sst version
```
Backup the v2 config with.
```
mv sst.config.ts sst.config.ts.bk
```
Init a v3 app.
```
npx sst init
```
Make sure to use the same app name.
Set the removal policy to retain. Similar to setDefaultRemovalPolicy in v2, you can configure the removal policy in sst.config.ts in v3.
sst.config.ts
```
app(input) {
  return {
    name: "my-sst-app",
    removal: input?.stage === "production" ? "retain" : "remove"
  };
}
```
By default, v3 has removal policy set to retain for the production stage, and remove for other stages.
Deploy an empty app to ensure the app is configured correctly.
```
npx sst deploy
```
Update the dev scripts for your frontend. Remove the sst bind from the dev script in your package.json. For example, for a Next.js app.
package.json
```
"dev": "sst bind next dev",
"dev": "next dev",
```
Remove any CDK related packages from your package.json.

Migrate stacks

Now before we start making changes to our constructs, you might have some stacks code in your sst.config.ts.

Take a look at the list below and apply the changes that matter to you.

Restructure

Since you don’t have to import the constructs and there are no stacks, you’ll need to change how your constructs are structured.

For example, in the monorepo notes app we made these changes.

export default $config({
  // ...

  async run() {
    await import("./infra/api");
    await import("./infra/storage");
    await import("./infra/frontend");
    const auth = await import("./infra/auth");

    return {
      UserPool: auth.userPool.id,
      Region: aws.getRegionOutput().name,
      IdentityPool: auth.identityPool.id,
      UserPoolClient: auth.userPoolClient.id,
    };
  }
}

import { SSTConfig } from "sst";
import { ApiStack } from "./stacks/ApiStack";
import { AuthStack } from "./stacks/AuthStack";
import { StorageStack } from "./stacks/StorageStack";
import { FrontendStack } from "./stacks/FrontendStack";

export default {
  // ...

  stacks(app) {
    app
      .stack(StorageStack)
      .stack(ApiStack)
      .stack(AuthStack)
      .stack(FrontendStack);
  }
} satisfies SSTConfig;

We store our infrastructure files in the infra/ directory in v3. You can refer to the demo notes app to see how these are structured.

Migrate runtime

For your runtime code, your functions and frontend; there are fairly minimal changes. The clients or the JS SDK have been reorganized.

You can make these changes now or as you are migrating each construct. Check out the steps below.

Migrate constructs

Constructs in v2 have their equivalent components in v3. Constructs fall into roughly these 3 categories:

Transient — these don’t contain data, like Function, Topic, or Queue.
Data — these contain application data, like RDS, Table, or Bucket.
Custom domains — these have custom domains configured, like Api, StaticSite, or NextjsSite.
Subscribers — these are constructs that subscribe to other constructs, like the Bucket, Queue, or Table subscribers.

We’ll go over each of these types and copy our v2 constructs over as v3 components.

Transient constructs

Constructs like Function, Cron, Topic, Queue, and KinesisStream do not contain data. They can be recreated in the v3 app.

Simply copy them over using the reference below.

Data constructs

Constructs like RDS, Table, Bucket, and Cognito contain data. If you do not need to keep the data, you can recreate them like what you did above. This is often the case for non-production stages.

However, for production stages, you need to import the underlying AWS resource into the v3 app.

For example, here are the steps for importing an S3 bucket named app-prod-MyBucket.

Import the resource

Say the bucket is defined in SST v2, and the bucket name is app-prod-MyBucket.

const bucket = new Bucket(stack, "MyBucket");

You can use the import and transform props to import it.

const bucket = new sst.aws.Bucket("MyBucket", {
  transform: {
    bucket: (args, opts) => {
      args.bucket = "app-prod-MyBucket";
      opts.import = "app-prod-MyBucket";
    },
    cors: (args, opts) => {
      opts.import = "app-prod-MyBucket";
    },
    policy: (args, opts) => {
      opts.import = "app-prod-MyBucket";
    },
    publicAccessBlock: (args, opts) => {
      opts.import = "app-prod-MyBucket";
    }
  }
});

Import is a process of bringing previously created resources into your SST app and allowing it to manage it moving forward. Learn more about importing resources.

Deploy

You’ll get an error if the resource configurations in your code does not match the exact configuration of the bucket in your AWS account.

This is good because we don’t want to change our old resource.
Update props

In the error message, you’ll see the props you need to change. Add them to the corresponding transform block.

And deploy again.

After the bucket has been imported, the v2 app can still make changes to the resource. If you try to remove the v2 app or remove the bucket from the v2 app, the S3 bucket will get removed. To prevent this, ensure that had the removal policy in the v2 app to retain.

Constructs with custom domains

Constructs like the following have custom domains.

Frontends like StaticSite, NextjsSite, SvelteKitSite, RemixSite, AstroSite, SolidStartSite
APIs like Api, ApiGatewayv1, AppSyncApi, WebSocketApi
Service

For non-prod stages you can just recreate them.

However, if they have a custom domain, you need to deploy them in steps to avoid any downtime.

First, create the resource in v3 without a custom domain. So for Nextjs for example.
- v3
- v2
sst.config.ts
new sst.aws.Nextjs("MySite");
sst.config.ts
new NextjsSite(stack, "MySite", { customDomain: "domain.com" });
Deploy your v3 app.
When you are ready, flip the domain using the override prop.
sst.config.ts
```
new sst.aws.Nextjs("MySite", {
  domain: {
   name: "domain.com",
   dns: sst.aws.dns({ override: true })
});
```
This updates the DNS record to point to your new Next.js app.

And deploy again.

After the DNS record has been overridden, the v2 app can still make changes to it. If you try to remove the v2 app, the record will get removed. To prevent this, ensure that the removal policy in the v2 app to retain.

Subscriber constructs

Many constructs have subscribers that help with async processing. For example, the Queue has a consumer, Bucket has the notification, and Table constructs have streams. You can recreate the constructs in your v3 app.

However recreating the subscribers for a production stage with an imported resource is not straight forward:

Recreating the consumer for an imported Queue will fail because a Queue can only have 1 consumer.
And, recreating the consumer for an imported DynamoDB Table will result in double processing. As in, an event will be processed both in your v2 and v3 app.

Here’s how we recommend getting around this.

Deploy the v3 app without the subscribers. Either by commenting out the .subscribe() call, or by returning early in the subscriber function.
When you are ready to flip, remove the subscribers in the v2 app and deploy.
Add the subscribers to the v3 app and deploy.

This ensures that the same subscriber is only attached once to a resource.

Clean up

Now that your v3 app is handling production traffic. We can optionally go clean up a few things from the v2 app.

The resources that were recreated in v3, the ones that were not imported, can now be removed. However, since we have v2 app set to retain, this is going to be a manual process.

You can go to the CloudFormation console, look at the list of resources in your v2 app’s stacks and remove them manually.

Finally, when you run sst remove for your v2 app, it’ll remove the CloudFormation stacks as well.

CI/CD

You probably have git push to deploy or CI/CD set up for your apps. If you are using Github Actions; there shouldn’t be much of a difference between v2 and v3.

If you are using Seed to deploy your v2 app; then you’ll want to migrate to using Autodeploy on the SST Console. We are currently not planning to support v3 on Seed.

There are a couple of key reasons to Autodeploy through the Console:

The builds are run in your AWS account.
You can configure your workflow through your sst.config.ts.
And you can see which resources were updated as a part of the deploy.

To enable Autodeploy on the Console, you’ll need to:

Create a new account on the Console — console.sst.dev
Link your AWS account
Connect your repo
Configure your environments
And git push

Learn more about Console and Autodeploy.

sst.config.ts

Listed below are some of the changes to your sst.config.ts in general.

No imports

All the constructs or components are available in the global context. So there’s no need to import anything. Your app’s package.json only needs the sst package. There are no extra CDK or infrastructure related packages.

Globals

There are a couple of global variables, $app and $dev that replace the app argument that’s passed into the stacks() method of your sst.config.ts.

$app.name gives you the name of app. Used to be app.name.
$app.stage gives you the name of stage. Used to be app.stage.
$dev === true tells you if you are in dev mode. Used to be app.mode === "dev.
$dev === false tells you if it’s being deployed. Used to be app.mode === "deploy.
There is no app.mode === remove replacement since your components are not evaluated on sst remove.
There is no app.region since in v3 you can deploy resources to different regions or AWS profiles or providers. To get the default AWS provider you can use aws.getRegionOutput().name.

No stacks

Also since there are no stacks. You don’t have access to the stack argument inside your stack function. And no stack.addOutputs({}) method.

You can still group your constructs or components in files. But to output something you return in the run method of your config.

async run() {
  const auth = await import("./infra/auth");

  return {
    UserPool: auth.userPool.id,
    IdentityPool: auth.identityPool.id,
    UserPoolClient: auth.userPoolClient.id
  };
}

Defaults

The set of methods that applied defaults to all the functions in your app like; addDefaultFunctionBinding, addDefaultFunctionEnv, addDefaultFunctionPermissions, and setDefaultFunctionProps can be replaced with the global $transform.

$transform(sst.aws.Function, (args, opts) => {
  // Set the default if it's not set by the component
  if (args.runtime === undefined) {
    args.runtime = "nodejs18.x";
  }
})

Learn more about $transform.

Clients

The Node.js client, now called the JS SDK has a couple of minor changes.

Update sst to the latest version in your package.json. If you have a monorepo, make sure to update sst in all your packages.

Bind

In SST v3, you access all bound or linked resources through the Resource module.

Say you link a bucket to a function.

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

new sst.aws.Function("MyFunction", {
  handler: "src/lambda.handler",
  link: [bucket]
});

const bucket = new Bucket(stack, "MyBucket");

new Function(stack, "MyFunction", {
  handler: "src/lambda.handler",
  bind: [bucket]
});

In your function you would access it like so.

import { Resource } from "sst";

console.log(Resource.MyBucket.name);

import { Bucket } from "sst/node/bucket";

console.log(Bucket.MyBucket.bucketName);

Config

The same applies to Config as well. Let’s look at a secret.

const secret = new sst.Secret("MySecret");

new sst.aws.Function("MyFunction", {
  handler: "src/lambda.handler",
  link: [secret]
});

const secret = new Config.Secret(stack, "MySecret");

new Function(stack, "MyFunction", {
  handler: "src/lambda.handler",
  bind: [secret]
});

And in your function you access it in the same way.

import { Resource } from "sst";

console.log(Resource.MySecret.value);

import { Config } from "sst/node/config";

console.log(Config.MySecret);

Handlers

In v2, some modules in the Node client had handlers and hooks.

import { ApiHandler } from "sst/node/api";

export const handler = ApiHandler((event) => { });

These were experimental and are not currently supported in v3. To continue using them you can import them by first adding it to your package.json.

{
  "sstv2": "npm:sst@^2",
  "sst": "^3"
}

This means that you have both v2 and v3 installed in your project. Since, they both have an sst binary, you want to make sure v3 takes precedence. So v3 should be listed after v2.

And then import them via the sstv2 alias.

import { ApiHandler } from "sstv2/node/api";

export const handler = ApiHandler((event) => { });

Constructs

Below shows the v3 component version of a v2 construct.

Api

const api = new sst.aws.ApiGatewayV2("MyApi", {
  domain: "api.example.com"
});

api.route("GET /", "src/get.handler");
api.route("POST /", "src/post.handler");

const api = new Api(stack, "MyApi", {
  customDomain: "api.example.com"
});

api.addRoutes(stack, {
  "GET /": "src/get.main",
  "POST /": "src/post.handler"
});

RDS

new sst.aws.Postgres("MyDatabase", {
  version: "15.5",
  databaseName: "acme"
});

new RDS(stack, "MyDatabase", {
  engine: "postgresql15.5",
  defaultDatabaseName: "acme",
  migrations: "path/to/migration/scripts"
});

For migrations, we recommend using Drizzle Kit. Check out our Drizzle example.

Cron

new sst.aws.Cron("MyCronJob", {
  schedule: "rate(1 minute)",
  job: "src/cron.handler"
});

new Cron(stack, "MyCronJob", {
  schedule: "rate(1 minute)",
  job: "src/cron.handler"
});

Table

const table = new sst.aws.Dynamo("MyTable", {
  fields: {
    id: "string"
  },
  primaryIndex: { hashKey: "id" }
});

table.subscribe("src/subscriber.handler");

const table = new Table(stack, "MyTable", {
  fields: {
    id: "string"
  },
  primaryIndex: { partitionKey: "id" }
});

table.addConsumers(stack, {
  consumer: "src/subscriber.handler"
});

Topic

const topic = new sst.aws.SnsTopic("MyTopic");

topic.subscribe("src/subscriber.handler");

const topic = new Topic(stack, "MyTopic");

topic.addSubscribers(stack, {
  subscriber: "src/subscriber.handler"
});

Queue

const queue = new sst.aws.Queue("MyQueue");

queue.subscribe("src/subscriber.handler");

const queue = new Queue(stack, "MyQueue");

queue.addConsumer(stack, "src/subscriber.handler");

Config

The Config construct is now broken into a Secret component and v3 has a separate way to bind any value or parameter.

Secret

const secret = new sst.Secret("MySecret");

const secret = new Config.Secret(stack, "MySecret");

There’s also a slight change to the CLI for setting secrets.

npx sst secret set MySecret sk_test_abc123

npx sst secrets set MySecret sk_test_abc123

Parameter

The Linkable component lets you bind or link any value.

const secret = new sst.Linkable("MyParameter", {
  properties: { version: "1.2.0" }
});

const secret = new Config.Parameter(stack, "MyParameter", {
  value: "1.2.0"
});

In your function you’d access this using.

import { Resource } from "sst";

console.log(Resource.MyParameter.version);

import { Config } from "sst/node/config";

console.log(Config.MyParameter);

Bucket

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

bucket.subscribe("src/subscriber.handler");

const bucket = new Bucket(stack, "MyBucket");

bucket.addNotifications(stack, {
  notification: "src/notification.main"
});

Service

const cluster = new sst.aws.Cluster("MyCluster", {
  vpc: {
    id: "vpc-0d19d2b8ca2b268a1",
    securityGroups: ["sg-0399348378a4c256c"],
    publicSubnets: ["subnet-0b6a2b73896dc8c4c", "subnet-021389ebee680c2f0"],
    privateSubnets: ["subnet-0db7376a7ad4db5fd ", "subnet-06fc7ee8319b2c0ce"]
  }
});

cluster.addService("MyService", {
  public: {
    domain: "my-app.com",
    ports: [
      { listen: "80/http" }
    ]
  }
});

new Service(stack, "MyService", {
  customDomain: "my-app.com",
  path: "./service",
  port: 80,
  cdk: {
    vpc: Vpc.fromLookup(stack, "VPC", {
      vpcId: "vpc-0d19d2b8ca2b268a1"
    })
  }
});

Cognito

const userPool = new sst.aws.CognitoUserPool("MyUserPool");

const client = userPool.addClient("MyClient");

new sst.aws.CognitoIdentityPool("MyIdentityPool", {
  userPools: [{
    userPool: userPool.id,
    client: client.id
  }]
});

new Cognito(stack, "MyAuth");

Function

new sst.aws.Function("MyFunction", {
  handler: "src/lambda.handler"
});

new Function(stack, "MyFunction", {
  handler: "src/lambda.handler"
});

AstroSite

new sst.aws.Astro("MyWeb", {
  domain: "my-app.com"
});

new AstroSite(stack, "MyWeb", {
  customDomain: "my-app.com"
});

StaticSite

new sst.aws.StaticSite("MyWeb", {
  domain: "my-app.com"
});

new StaticSite(stack, "MyWeb", {
  customDomain: "my-app.com"
});

RemixSite

new sst.aws.Remix("MyWeb", {
  domain: "my-app.com"
});

new RemixSite(stack, "MyWeb", {
  customDomain: "my-app.com"
});

NextjsSite

new sst.aws.Nextjs("MyWeb", {
  domain: "my-app.com"
});

new NextjsSite(stack, "MyWeb", {
  customDomain: "my-app.com"
});

AppSyncApi

const api = new sst.aws.AppSync("MyApi", {
  schema: "schema.graphql",
  domain: "api.domain.com"
});

const lambdaDS = api.addDataSource({
  name: "lambdaDS",
  lambda: "src/lambda.handler"
});
api.addResolver("Query user", {
  dataSource: lambdaDS.name
});

const api = new AppSyncApi(stack, "MyApi", {
  schema: "graphql/schema.graphql",
  customDomain: "api.example.com"
});

api.addDataSources(stack, {
  lambdaDS: "src/lambda.handler"
});
api.addResolvers(stack, {
  "Query user": "lambdaDS"
});

SvelteKitSite

new sst.aws.SvelteKit("MyWeb", {
  domain: "my-app.com"
});

new SvelteKitSite(stack, "MyWeb", {
  customDomain: "my-app.com"
});

SolidStartSite

new sst.aws.SolidStart("MyWeb", {
  domain: "my-app.com"
});

new SolidStartSite(stack, "MyWeb", {
  customDomain: "my-app.com"
});

WebSocketApi

const api = new sst.aws.ApiGatewayWebSocket("MyApi", {
  domain: "api.example.com"
});

api.route("$connect", "src/connect.handler");
api.route("$disconnect", "src/disconnect.handler");

const api = new WebSocketApi(stack, "MyApi", {
  customDomain: "api.example.com"
});

api.addRoutes(stack, {
  $connect: "src/connect.handler",
  $disconnect: "src/disconnect.handler"
});

KinesisStream

const stream = new sst.aws.KinesisStream("MyStream");

stream.subscribe("src/subscriber.handler");

const stream = new KinesisStream(stack, "MyStream");

stream.addConsumers(stack, {
  consumer: "src/subscriber.handler"
});

ApiGatewayV1Api

const api = new sst.aws.ApiGatewayV1("MyApi", {
  domain: "api.example.com"
});

api.route("GET /", "src/get.handler");
api.route("POST /", "src/post.handler");
api.deploy();

const api = new ApiGatewayV1Api(stack, "MyApi", {
  customDomain: "api.example.com"
});

api.addRoutes(stack, {
  "GET /": "src/get.handler",
  "POST /": "src/post.handler"
});

Congrats on getting through the migration.

If you find any errors or if you’d like to add some details to this guide, feel free to Edit this page and submit a PR.