What is Ion
Ion is a new deployment engine for SST.
Ion is a new engine for deploying SST apps. It uses Pulumi and Terraform, as opposed to CDK and CloudFormation.
Ion is generally available and recommended for new SST users. We are working on a migration path for SST v2 users. Once Ion is stable, it’ll be released as SST v3. Read the full announcement.
Aside from the underlying engine, there are a couple of other differences between SST v2 and Ion.
- There are no “stacks” or stack resource limits.
- There are no npm packages, just a CLI and the
sst.config.ts
. - Resource binding is now called linking and works across cloud providers.
- The
bind
command has been merged into thedev
command. You won’t need to run both of them.
If you are new to SST, here’s how it works.
SST is a framework that makes it easy to build modern full-stack applications on your own infrastructure.
Frontend
You start by defining, in code, the frontend you are using. Or if you don’t have a frontend, you can start with an API.
Support for other frontends are on the roadmap.
Backend
Just like configuring the frontend, you can configure backend features in code. Features like cron jobs, buckets, queues, databases, and more.
You can check out the full list of components on the sidebar.
Infrastructure
The above snippets are called Components. They are a way of defining the features of your application in code. You can define any feature of your application with them.
In the above examples, they create the necessary infrastructure in your AWS account. All without using the AWS Console.
Learn more about Components.
Configure
SST’s components come with sensible defaults designed to get you started. But they can also be configured completely.
For example, the sst.aws.Function
can be configured with all the common Lambda function props.
But with SST you can take it a step further and transform how the Function component creates its low level infrastructure. For example, the Function component also creates an IAM Role. You can transform the IAM Role using the transform
prop.
Read more about transforms.
Extend
If you want to add a feature to your app that’s not supported by SST’s components yet, you can use Pulumi components directly in your SST app. This is because components in SST are built on Pulumi components.
You can also use any provider in the Pulumi Registry. Read more about providers.
Link resources
Once you’ve added a couple of features, SST can help you link them together. This is great because you won’t need to hardcode anything in your app.
Let’s say your app has a Next.js frontend and an S3 bucket for file uploads. You can link
the bucket to your Next.js app.
You can then use SST’s SDK to access the S3 bucket in your Next.js app.
Learn more about resource linking.
Project structure
We’ve looked at a couple of different types of files. Let’s take a step back and see what an SST app looks like in practice.
Drop-in mode
The simplest way to run SST is to use it as a part of your frontend. This is called drop-in mode. For example, if you are using Next.js, you can add a sst.config.ts
file to the root.
View an example Next.js app using SST in drop-in mode.
Monorepo
Alternatively, you can use SST in a monorepo. This is useful if you have multiple frontends or you are working on a large project. In this case the sst.config.ts
is in the root of your monorepo.
Learn more about our monorepo setup.
CLI
To make this all work, Ion comes with a CLI that you install globally.
The CLI currently supports macOS, Linux, and WSL.
Dev
The CLI includes a dev
command that starts a local development environment.
It lets you make and test changes to your function live, without having to redeploy them.
You can also use this command to start your frontend locally, and it’ll automatically load your linked resources in your frontend’s environment.
Deploy
When you’re ready to deploy your app, you can use the deploy
command.
Personal stage
By default, your app is deployed to your personal stage. The name of your personal stage is your username in the local machine. This is cached in the .sst/stage
file.
You can override this to deploy to separate stages or environments.
Environments
The deploy
command can also deploy your app to a specific stage or environment.
This lets you create separate environments for development, production, pull-requests, or branches. Learn more about stages.
Console
Once your app is in production, you can use the SST Console to monitor and manage your app — console.sst.dev