Skip to main content

Quick Start

SST is a collection of npm packages that allow you to define your infrastructure, write functions, and connect it to your frontend.

0. Prerequisites​

SST is built with Node, so make sure your local machine has it installed; Node.js 14 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

Pick a starter​

This will prompt you to select a starter.

? What kind of project do you want to create? (Use arrow keys)
❯ graphql
  minimal
  examples

The graphql starter is a full-stack TypeScript app organized as a monorepo. It comes with a GraphQL API, a frontend React app, and all of our best practices. Let's pick that.

Next, it will prompt you to select a database; either RDS (PostgreSQL or MySQL) or DynamoDB.

? Select a database (you can change this later or use both) (Use arrow keys)
  RDS (Postgres or MySQL)
❯ DynamoDB

Let's use DynamoDB for now. If you want to use PostgreSQL, check out our tutorial, we cover it in detail.

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 start

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.

==========================
 Starting Live Lambda Dev
==========================

SST Console: https://console.sst.dev/my-sst-app/Jay/local
Debug session started. Listening for requests...

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

Start the frontend​

The frontend in our starter is a React app created with Vite. Let's start it locally from the web/ directory.

cd web
npm run dev

Once complete, you can navigate to the URL in your output — http://localhost:3000/. You should see the homepage of our starter! It's a simple Reddit clone where you can post links.

info

Your frontend is automatically connected to your API on AWS.

Try posting a link.

SST starter homepage

If you check the developer console in your browser, you'll notice that it's making requests to an endpoint in AWS — https://cok8brhsqk.execute-api.us-east-1.amazonaws.com/graphql

Open the console​

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

Click on the DynamoDB tab on the left.

SST Console DynamoDB tab

You should see a row for the newly posted link. Note that, just like the GraphQL API above, the database is not running locally, it's on AWS.

3. Make a change​

Let's make a change to our API and see what the workflow is like. Replace the following in services/functions/graphql/types/article.ts.

services/functions/graphql/types/article.ts
fields: (t) => ({
  id: t.exposeID("articleID"),
  url: t.exposeString("url"),
- title: t.exposeString("title"),
+ title: t.field({
+   type: "String",
+   resolve: (article) => `🔥 ${article.title}`,
+ }),
}),

We are editing our GraphQL resolver to format the titles of our articles. Now if you refresh your browser.

SST starter updated homepage

Behind the scenes

Here's how this all works behind the scenes. All our infrastructure is defined in the stacks/ directory.

  1. Here we define our database in stacks/Database.ts using the Table construct.

    const table = new Table(stack, "table", {
      /** **/
    });

  2. We then define an API using the Api in stacks/Api.ts.

    const api = new ApiGateway(stack, "api", {
      /** **/
    });

    We pass our database details to the API so our functions can make queries to it.

    function: {
      permissions: [db.table],
      config: [db.TABLE_NAME],
    },

  3. Next we define our frontend in stacks/Web.ts using the ViteStaticSite construct.

    const site = new ViteStaticSite(stack, "site", {
      /** **/
    });

    And we pass in our API URL to the frontend.

    environment: {
      VITE_GRAPHQL_URL: api.url + "/graphql",
    },

  4. Finally, we tie these all together in stacks/index.ts.

    app.stack(Database).stack(Api).stack(Web);

    And we specify the directory with our functions code.

    srcPath: "services",

  5. Our function handlers are in the services/functions/ directory.

  6. Finally, our core domain logic or business logic is in the services/core/ directory. It's organized using Domain Driven Design.

The graphql/ directory is code-genned and allows us to share the backend types in our frontend. It should be committed to Git.

So to recap, our frontend is running locally and it's talking to our GraphQL API hosted on AWS. However we can make changes to the functions and they get live reloaded.

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.

Stack Jay-my-sst-app-Web
  Status: deployed
  Outputs:
    SITE: https://dzennbvva4xas.cloudfront.net
  site:
    VITE_GRAPHQL_URL: https://q14k5arhm8wl.execute-api.us-east-1.amazonaws.com/graphql

Our site is now live at SITE and it's talking to our GraphQL API at VITE_API_URL. You'll notice this is a completely new API endpoint.

You can also add custom domains to your app and API, 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.

info

By default, SST does not remove your DynamoDB table. This prevents accidental removals. You'll need to set the Removal Policy to force remove it.

6. Next steps​

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