Skip to main content

Quick Start

Take SST for a spin and create your first project.

0. Prerequisites​

SST is built with Node, so make sure your local machine has it installed; at least Node.js 16 and npm 7.

AWS credentials​

You also need to have an AWS account and AWS credentials configured locally. If you haven't already, follow these steps.

1. Create a new app​

Create a new SST app using the create-sst CLI.

npx create-sst@latest my-sst-app

Install dependencies​

Next install the dependencies.

cd my-sst-app
npm install

2. Start local environment​

Then start the Live Lambda local development environment.

npx sst dev

The first time you run this command in a project, you'll be prompted to enter a default stage name to use.

Pick a stage​

SST uses the stage names to namespace your resources.

Look like you’re running sst for the first time in this directory. Please enter
a stage name you’d like to use locally. Or hit enter to use the one based on
your AWS credentials (Jay):

Just hit Enter to select the default one.

Behind the scenes

The name spaced resources lets SST deploy multiple environments of the same app to the same AWS account. So you and your teammates can work together.

The stage name will be stored locally in a .sst/ directory. It's automatically ignored from Git.

The initial deploy can take a few minutes. It will deploy your app to AWS, and also setup the infrastructure to support your local development environment.

Once complete, you'll see something like this.

➜  App:     my-sst-app
   Stage:   Jay
   Console: https://console.sst.dev/my-sst-app/Jay/local

✔  Deployed:
   API
   ApiEndpoint: https://bmodl6wkkj.execute-api.us-east-1.amazonaws.com

Now our app has been deployed to AWS and it's connected to our local machine!

Open the console​

The sst dev command also powers a web based dashboard, called the SST Console. Head over to the URL above or simply — console.sst.dev

Select the API tab on the left, and click Send. This will make a request to the endpoint in AWS.

SST Console API tab

You should see a Hello world message in the response.

3. Make a change​

Let's make a change to our API and see what the workflow is like. Replace the following in packages/functions/src/lambda.ts.

packages/functions/src/lambda.ts
export const handler = ApiHandler(async (_evt) => {
  return {
-   body: `Hello world. The time is ${Time.now()}`,
+   body: "This is my awesome API!",
  };
});

Switch back to the SST Console, and click Send again.

SST Console API tab

You should see the updated message in the response.

4. Deploy to prod​

Once you are done working on your app locally, you are ready to go to production. We'll use the sst deploy command for this.

We don't want to use the same stage as our local environment since we want to separate our dev and prod environments. So we'll run the sst deploy command with the --stage option.

npx sst deploy --stage prod

This will take a few minutes to run and will create a complete new version of your app. Once complete you'll notice these outputs.

✔  Deployed:
   API
   ApiEndpoint: https://2q0mwp6r8d.execute-api.us-east-1.amazonaws.com

You'll notice this is a completely new API endpoint.

You can also add custom domains to your app, but we'll cover that in a separate tutorial.

5. Remove the app​

Finally to wrap this up, you can remove all your app all its resources from AWS.

npx sst remove
npx sst remove --stage prod

This removes the local and prod environments of your app.

6. Next steps​

If you are ready to dive into the details of SST, check out our tutorial.