In this guide we'll look at how to migrate a Serverless Framework app to SST.
Note that, this document is a work in progress. If you have experience migrating your Serverless Framework app to SST, please consider contributing.
SST has been designed to be incrementally adopted. This means that you can continue using your existing Serverless Framework app while slowly moving over resources to SST. By starting small and incrementally adding more resources, you can avoid a wholesale rewrite.
Let's assume you have an existing Serverless Framework app. To get started, we'll first set up a new SST project in the same directory.
To make it an easier transition, we'll start by merging your existing Serverless Framework app with a newly created SST app.
Your existing app can either have one service or be a monorepo with multiple services.
- In a temporary location, run
npx create-serverless-stack@latest my-sst-appor use the
--language typescriptoption if your project is in TypeScript.
- Copy the
sst.jsonfile and the
- Copy the
package.jsonfile in the new SST project root.
- Copy the
.gitignorefile and append it to your existing
- If you are using TypeScript, you can also copy the
Now your directory structure should look something like this. The
src/ directory is where all the Lambda functions in your Serverless Framework app are placed.
And from your project root you can run both the Serverless Framework and SST commands.
This also allows you to easily create functions in your new SST app by pointing to the handlers in your existing app.
Say you have a Lambda function defined in your
You can now create a function in your SST app using the same source.
Next, if you need to add a new service or resource to your Serverless Framework app, you can instead do it directly in SST.
For example, say you want to add a new SQS queue resource.
- Start by creating a new stack in the
lib/directory. Something like,
- Add the new stack to the list in
Now that you have two separate apps side-by-side, you might find yourself needing to reference stack outputs between each other.
To reference a Serverless Framework stack output in SST, you can use the
You might also want to reference a newly created resource in SST in Serverless Framework.
And finally, to reference stack outputs across stacks in your SST app.
The next step would be to use the resources that are created in your Serverless Framework app. You can reference them directly in your SST app, so you don't have to recreate them.
For example, if you've already created an SNS topic in your Serverless Framework app, and you want to add a new function to subscribe to it:
There are a couple of strategies if you want to migrate your Serverless Framework resources to your SST app.
This applies to API endpoints and it allows you to incrementally migrate API endpoints to SST.
Support for this strategy hasn't been implemented in SST yet.
Suppose you have a couple of routes in your
And you are ready to migrate the
/users endpoint but don't want to touch the other endpoints yet.
You can add the route you want to migrate, and set a catch all route to proxy requests the rest to the old API.
Now you can use the new API endpoint in your frontend application. And remove the old route from the Serverless Framework app.
This is suitable for migrating resources that don't have persistent data. So, SNS topics, SQS queues, and the like.
Imagine you have an existing SNS topic named
Create a new topic in SST called
MyTopic.sstand add a subscriber with the same function code.
Now in your app, start publishing to the
Remove the old
MyTopicresource from the Serverless Framework app.
Optionally, you can now create another new topic in SST called
MyTopic and follow the steps above to remove the temporary
Now for resources that have persistent data like DynamoDB and S3, it won't be possible to remove them and recreate them. For these cases you can leave them as-is, while migrating over the DynamoDB stream subscribers and S3 bucket event subscribers as a first step.
Here's an example for DynamoDB streams. Assume you have a DynamoDB table that is named based on the stage it's deployed to.
Now in SST, you can import the table and create an SST function to subscribe to its streams.
A lot of the commands that you are used to using in Serverless Framework translate well to SST.
SST also supports the
IS_LOCAL environment variable that gets set in your Lambda functions when run locally.
With the Serverless Framework you need to run the following command
serverless invoke local -f function_name to invoke a function locally.
With SST this can be done via PostMan, Hopscotch, curl or any other API client. However, with this event you are actually sending a request to API Gateway which then invokes your Lambda.
If you are using GitHub Actions, Circle CI, etc., to deploy Serverless Framework apps, you can now add the SST versions to your build scripts.
If you are using the Serverless Dashboard, you can try out Seed instead. It supports Serverless Framework and SST. So you can deploy the hybrid app that we've created here.
Seed has a fully-managed CI/CD pipeline, monitoring, real-time alerts, and deploys a lot faster thanks to the Incremental Deploys. It also gives you a great birds eye view of all your environments.
Following is a list of all the Lambda function triggers available in Serverless Framework. And the support status in SST (or CDK).
|API Gateway REST API||Available|
|Cognito User Pool||Available|
|Alexa Smart Home||Available|
|IoT Fleet Provisioning||Coming soon|
Serverless Framework supports a long list of popular plugins. In this section we'll look at how to adopt their functionality to SST.
To start with, let's look at the very popular serverless-offline plugin. It's used to emulate a Lambda function locally but it's fairly limited in the workflows it supports. There are also a number of other plugins that work with serverless-offline to support various other Lambda triggers.
sst start, you don't need to worry about using them anymore.
Let's look at the other popular Serverless Framework plugins and how to set them up in SST.
A list of examples showing how to use Serverless Framework triggers or plugins in SST.