Migrate From v2

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 Basics 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.

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:

  1. There are no stacks, all the resources are defined through the same function in the sst.config.ts.
  2. 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.
  3. 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:

  1. You cannot fall back to CDK constructs if something isn’t supported by SST. Instead there is the AWS provider from Pulumi that’s built on Terraform.
  2. 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.

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.

  1. 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.
  2. Test your non-prod version of your v3 app.
  3. Then for your prod stage, follow the steps below and make the import, domain, and subscriber changes.
  4. 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

  1. 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");

  1. Create a new branch in your repo for the upcoming changes.

  2. 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.

  1. Update SST to v3. Or set the version by hand in your package.json. Make sure to do this across all the packages in your repo.
npm update sst

Ensure v3 is installed.

npx sst version
  1. Backup the v2 config with.
mv sst.config.ts sst.config.ts.bk
  1. Init a v3 app.
npx sst init
  1. Set the removal policy to retain. Similar to setDefaultRemovalPolicy in v2, you can configure the removal policy in sst.config.ts in v3.
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.

  1. Deploy an empty app to ensure the app is configured correctly.
npx sst deploy
  1. 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.
"dev": "next dev",
  1. Remove any CDK related packages from your package.json.

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.

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.