Live

Live is a feature of SST that lets you test changes made to your functions in milliseconds. Your changes work without having to redeploy. And they can be invoked remotely.

Tip

By default, sst dev will run all the functions in your app “live”.

It works by proxying requests from your cloud provider to your local machine, executing it locally, and proxying the response back.

---

Advantages

This setup of running your functions locally and proxying the results back allows you to do a couple of things:

• Your changes are reloaded in under 10ms.
• You can set breakpoints to debug your function in your favorite IDE.
• Functions can be invoke remotely. For example, say https://my-api.com/hello is your API endpoint. Hitting that will run the local version of that function.
  • This applies to more than just APIs. Any cron job or async event that gets invoked remotely will also run your local function.
  • It allows you to very easily debug and test webhooks, since you can just give the webhook your API endpoint.
  • Supports all function triggers, there’s no need to mock an event.
• Uses the right IAM permissions, so if a Lambda fails on AWS due to the lack of IAM permissions, it would fail locally as well.

---

How it works

On AWS, Live uses IoT over WebSocket to communicate between your local machine and the remote Lambda function.

Note

Every AWS account comes with a AWS IoT Core endpoint by default.

This is roughly what the flow looks like:

1. When you run sst dev, it deploys your app and replaces the Lambda functions with a stub version.
2. It also starts up a local WebSocket client and connects to your AWS accounts’ IoT endpoint.
3. When a Lambda function in your app is invoked, it publishes an event, where the payload is the Lambda function request.
4. Your local WebSocket client receives this event. It publishes an event acknowledging that it received the request.
5. Next, it runs the local version of the function and publishes an event with the function response as the payload. The local version is run as a Node.js Worker.
6. Finally, the stub Lambda function receives the event and responds with the payload.

Tip

The stub function that’s deployed uses a different runtime than the actual function.

---

SST_LIVE

When a function is running live it sets the SST_LIVE environment variable to true.

src/lambda.js

export async function main(event) {
  const body = process.env.SST_LIVE ? "Hello, Live!" : "Hello, World!";

  return {
    body,
    statusCode: 200,
    headers: { "Content-Type": "text/plain" }
  };
}

---

Connect to a local DB

You might have some resources that are only available locally. For example, a local database server.

To connect to these, you can check the SST_LIVE environment variable.

const dbHost = process.env.SST_LIVE
  ? "localhost"
  : "amazon-string.rds.amazonaws.com";

---

Cost

AWS IoT that powers Live is completely serverless. So you don’t get charged when it’s not in use.

It’s also pretty cheap. With a free tier of 500k events per month and roughly $1.00 per million for the next billion messages. You can check out the details here.

This approach has been economical even for large teams with dozens of developers.

---

Privacy

All the data stays between your local machine and your AWS account. There are no 3rd party services that are used.

Live also supports connecting to AWS resources inside a VPC.

---

Using a VPC

By default your local functions cannot connect to resources in a VPC. You’ll need to:

1. Setup a VPN connection from your local machine to your VPC network. You can use the AWS Client VPN service to set it up. Follow the Mutual authentication section in this doc to setup the certificates and import them into your Amazon Certificate Manager.
2. Then create a Client VPC Endpoint, and associate it with your VPC.
3. And, finally install Tunnelblick locally to establish the VPN connection.

Note that, the AWS Client VPC service is billed on an hourly basis but it’s fairly inexpensive. Read more on the pricing here.

---

Breakpoints

Since Live runs your functions locally, you can set breakpoints and debug your functions in your favorite IDE.

For VS Code, add the following Launch Configuration to .vscode/launch.json.

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug SST Live",
      "type": "node",
      "request": "launch",
      "runtimeArgs": ["dev"],
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"],
      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst"
    }
  ]
}