Upgrade Guide
Upgrade guide for all notable SST releases.
To view the latest release and all historical releases, head over to our GitHub release page.
Upgrade to v2.0
The 2.0 upgrade is primarily ergonomic and should not result in any infrastructure changes.
Packages
SST is now a monorepo, remove all packages referencing
@serverless-stack/resources
@serverless-stack/cli
@serverless-stack/node
and@serverless-stack/static-site-env
. Install thesst
package{
"devDependencies": {
- "@serverless-stack/resources": "xxx",
- "@serverless-stack/cli": "xxx",
- "@serverless-stack/static-site-env": "xxx",
- "@serverless-stack/node": "xxx",
+ "sst": "2.x",
+ "constructs": "10.1.156"
}
}Ensure
"constructs": "10.1.156"
is installedIn your stacks code replace all imports from
@serverless-stack/resources
tosst/constructs
- import { Function } from "@serverless-stack/resources"
+ import { Function } from "sst/constructs"If you were using
@serverless-stack/static-site-env
for your frontend, replace it with thesst env '<command>'
command"scripts": {
- "dev": "static-site-env -- vite dev",
+ "dev": "sst env vite dev",
}
Config
sst.json
is now specified as a sst.config.ts
file. The main
field has been replaced with a function that can directly import your stacks.
import type { SSTConfig } from "sst"
import { Api } from "./stacks/Api.js"
import { Dynamo } from "./stacks/Dynamo.js"
export default {
config(input) {
return {
name: "myapp",
region: "us-east-1",
profile: "my-company-dev"
}
},
stacks(app) {
app.setDefaultFunctionProps({
runtime: "nodejs16.x",
architecture: "arm_64",
})
app
.stack(Api)
.stack(Dynamo)
},
} satisfies SSTConfig
CLI
sst start
has been renamed tosst dev
(although both will work)sst load-config
has been removed — see v1.16
Constructs
Function
- Default runtime is
nodejs18.x
- Default format is
esm
- We've made changes to the
FunctionProps
API so you should be seeing type errors around thebundle
property. Most of the options there have been moved to anodejs
property instead.const fn = new Function(stack, "fn", {
- bundle: {
- format: "esm",
- },
+ nodejs: {
+ format: "esm"
+ }
}) - We've removed the need for
srcPath
in function definitions but all your handler paths need to be specified relative to the root of the project.new Function(stack, "fn", {
- srcPath: "services",
- handler: "path/to/func.handler"
+ handler: "services/path/to/func.handler"
}) - Removed
config
prop — see v1.16
- Default runtime is
Api: removed the
pothos
route type — see v1.18StaticSite, NextjsSite, and RemixSite
- Following attributes were renamed:
bucketArn
renamed tocdk.bucket.bucketArn
bucketName
renamed tocdk.bucket.bucketName
distributionId
renamed tocdk.distribution.distributionId
distributionDomain
renamed tocdk.distribution.distributionDomainName
const site = new StaticSite(stack, "MySite");
- site.bucketArn
- site.bucketName
- site.distributionId
- site.distributionDomain
+ site.cdk.bucket.bucketArn
+ site.cdk.bucket.bucketName
+ site.cdk.distribution.distributionId
+ site.cdk.distribution.distributionDomainName - Running
sst dev
no longer deploys a placeholder sitesite.url
isundefined
in dev modesite.customDomainUrl
isundefined
in dev mode
waitForInvalidation
now defaults tofalse
- Following attributes were renamed:
NextjsSite
- in SST v1, the
NextjsSite
construct uses the@sls-next/lambda-at-edge package
package from theserverless-next.js
project to build and package your Next.js app so that it can be deployed to AWS. The project is no longer maintained. SST v2 uses theOpenNext
project. You can still use the oldNextjsSite
construct like this:import { NextjsSite } from "sst/constructs/deprecated";
commandHooks.afterBuild
renamed tobuildCommand
new NextjsSite(stack, "NextSite", {
path: "path/to/site",
- commandHooks: {
- afterBuild: ["npx next-sitemap"],
- }
+ buildCommand: "npx open-next@latest build && npx next-sitemap"
});
- in SST v1, the
Removed ViteStaticSite and ReactStaticSite — see v1.18
Removed GraphQLApi — see v1.18
Function code
- In your functions code replace all imports from
@serverless-stack/node/xxx
tosst/node/xxx
- import { Bucket } from "@serverless-stack/node/bucket"
+ import { Bucket } from "sst/node/bucket" - If you're using function binding we moved type generation into a
.sst
folder. To include this place ansst-env.d.ts
file in any package that needs the types that contains the following:Make sure you specify the path correctly/// <reference path="../.sst/types/index.ts" />
Upgrade to v1.18
Constructs
Api: The
pothos
route type is renamed tographql
, and will be removed in SST v2.new Api(stack, "api", {
routes: {
"POST /graphql": {
- type: "pothos",
+ type: "graphql",
function: handler: "functions/graphql/graphql.ts",
- schema: "backend/functions/graphql/schema.ts",
- output: "graphql/schema.graphql",
- commands: [
- "./genql graphql/graphql.schema graphql/
- ]
+ pothos: {
+ schema: "backend/functions/graphql/schema.ts",
+ output: "graphql/schema.graphql",
+ commands: [
+ "./genql graphql/graphql.schema graphql/
+ ]
+ }
}
}
});GraphQLApi: The
GraphQLApi
construct is deprecated, and will be removed in SST v2. Use theApi
construct with agraphql
route instead.- new GraphQLApi(stack, "api", {
- server: "src/graphql.handler",
- });
+ new Api(stack, "api", {
+ routes: {
+ "POST /": {
+ type: "graphql",
+ function: "src/graphql.handler",
+ }
+ }
+ });ViteStaticSite: The
ViteStaticSite
construct is deprecated, and will be removed in SST v2. Use theStaticSite
construct instead. SpecifybuildCommand
,buildOutput
, and renametypesPath
tovite.types
.- new ViteStaticSite(stack, "frontend", {
+ new StaticSite(stack, "frontend", {
path: "path/to/src",
+ buildCommand: "npm run build", // or "yarn build"
+ buildOutput: "dist",
customDomain: "mydomain.com",
environment: {
VITE_API_URL: api.url,
},
- typesPath: "types/my-env.d.ts",
+ vite: {
+ types: "types/my-env.d.ts",
+ }
});ReactStaticSite: The
ReactStaticSite
construct is deprecated, and will be removed in SST v2. Use theStaticSite
construct instead. SpecifybuildCommand
andbuildOutput
.- new ReactStaticSite(stack, "frontend", {
+ new StaticSite(stack, "frontend", {
path: "path/to/src",
+ buildCommand: "npm run build", // or "yarn build"
+ buildOutput: "build",
customDomain: "mydomain.com",
environment: {
REACT_APP_API_URL: api.url,
},
});
Upgrade to v1.16
Resource Binding was introduced in this release. It simplifies accessing the resources in your app. For example, here's how we bind the bucket to the function:
const bucket = new Bucket(stack, "myFiles");
new Function(stack, "myFunction", {
handler: "lambda.handler",
- environment: {
- BUCKET_NAME: bucket.bucketName,
- },
- permissions: [bucket],
+ bind: [bucket],
});
And here's how we access it in our function.
+ import { Bucket } from "@serverless-stack/node/bucket";
- process.env.BUCKET_NAME
+ Bucket.myFiles.bucketName
Following are the steps to upgrade.
CLI
The path for the SSM parameters that stores the secrets has changed. So you'll need to run
sst deploy
orsst dev
before using thesst secrets
CLI.The
sst load-config
command is being renamed tosst bind
and will be removed in SST v2- sst load-config -- vitest run
+ sst bind -- vitest run
Constructs
Construct IDs need to be unique and match the pattern
[a-zA-Z]([a-zA-Z0-9-_])+
. If you have constructs with clashing IDs, change to a unique ID. And pass the old ID intocdk.id
to ensure CloudFormation does not recreate the resource.For example, if you have two buckets with the same id.
- new Bucket(stack), "bucket");
- new Bucket(stack), "bucket");
+ new Bucket(stack), "usersFiles", {
+ cdk: { id: "bucket" },
+ });
+ new Bucket(stack), "adminFiles", {
+ cdk: { id: "bucket" },
+ });Function/Job: Pass Secrets and Parameters into
bind
instead ofconfig
. Theconfig
option will be removed in SST v2.new Function(stack, "myFn", {
- config: [MY_STRIPE_KEY],
+ bind: [MY_STRIPE_KEY],
});
new Job(stack, "myJob", {
- config: [MY_STRIPE_KEY],
+ bind: [MY_STRIPE_KEY],
});Function/Job: Pass SST Constructs into
bind
instead ofpermissions
to grant permissions.permissions
will not accept SST Constructs in SST v2.new Function(stack, "myFn", {
- permissions: [myTopic],
+ bind: [myTopic],
});
new Job(stack, "myJob", {
- permissions: [myTopic],
+ bind: [myTopic],
});App/Stack: Pass Secrets and Parameters into
addDefaultFunctionBinding
instead ofaddDefaultFunctionConfig
.addDefaultFunctionConfig
will be removed in SST v2- app.addDefaultFunctionConfig([MY_STRIPE_KEY]);
+ app.addDefaultFunctionBinding([MY_STRIPE_KEY]);
- stack.addDefaultFunctionConfig([MY_STRIPE_KEY]);
+ stack.addDefaultFunctionBinding([MY_STRIPE_KEY]);App/Stack: Pass SST Constructs into
addDefaultFunctionBinding
instead ofaddDefaultFunctionPermissions
to grant permissions.addDefaultFunctionPermissions
will not accept SST Constructs in SST v2.- app.addDefaultFunctionPermissions([myTopic]);
+ app.addDefaultFunctionBinding([myTopic]);
- stack.addDefaultFunctionPermissions([myTopic]);
+ stack.addDefaultFunctionBinding([myTopic]);
Client
Change
Job.run("myJob")
toJob.myJob.run()
in your functions code.- Job.run("myJob", { payload });
+ Job.myJob.run({ payload });
Upgrade to v1.10
Constructs
The old
Auth
construct has been renamed toCognito
construct.- new Auth(stack, "auth", {
+ new Cognito(stack, "auth", {
login: ["email"],
});
Upgrade to v1.3
Constructs
Auth:
attachPermissionsForAuthUsers()
andattachPermissionsForUnauthUsers()
now take a scope as the first argument.const auth = new Auth(stack, "auth", {
login: ["email"],
});
- auth.attachPermissionsForAuthUsers(["s3", "sns"]);
+ auth.attachPermissionsForAuthUsers(auth, ["s3", "sns"]);
- auth.attachPermissionsForUnauthUsers(["s3"]);
+ auth.attachPermissionsForUnauthUsers([auth, "s3"]);