Skip to main content

Clients

Helper packages for your Node.js Lambda functions.


Installation

Install the @serverless-stack/node package in your services/ directory.

npm install @serverless-stack/node

Or the directory where your functions are placed.


Exports

The @serverless-stack/node package is made up of a collection of modules. Like the @serverless-stack/node/api, @serverless-stack/node/bucket, etc. Each of these modules has 3 types of exports:


Properties

The properties in each module helps you access the resources that are bound to the function.

For example, if you bind a Bucket to the function:

// Create an S3 bucket
const bucket = new Bucket(stack, "myFiles");

new Function(stack, "myFunction", {
handler: "lambda.handler",
// Bind to function
bind: [bucket],
});

You can access the bucket name in your function by importing Bucket from the @serverless-stack/node/bucket module:

import { Bucket } from "@serverless-stack/node/bucket";

console.log(Bucket.myFiles.bucketName);
info

Due to the use of top-level await, your functions need to be bundled in the esm format. If you created your app using create-sst, the bundle format is likely already set to esm. Here's how to set the Function bundle format.


Handlers

The handlers in each module is a function that can wrap around Lambda function handlers. Here's an example of the API handler.

import { ApiHandler } from "@serverless-stack/node/api";

export const handler = ApiHandler((event) => {
// ...
});
caution

Handlers are being actively worked on and are subject to change.

Each handler has a specific purpose but they share a couple of things in common:

  1. Provide proper typesafety.
  2. They also initialize SST's context system to power our Hooks.

Hooks

The hooks in each module are functions that you can call anywhere in your application code. It has access to things that are specific to the current invocation. This avoids having to pass things through multiple function calls down to our domain code.

caution

Hooks are being actively worked on and are subject to change.

For example, you can call the useSession hook to get access to the current user session in APIs that need authentication.

import { useSession } from "@serverless-stack/node/auth";

const session = useSession();

if (session.type === "user) {
console.log(session.properties.userID);
}

Behind the scenes, Hooks are powered by a SST's context system. Handlers like the GraphQLHandler and the AuthHandler create a global variable that keeps track of the "context" for the current request. This context object gets reset on every invocation.

Hooks are an alternative to middleware solutions like Middy. They provide better typesafety and will be familiar to developers that've used Hooks in frontend frameworks.


Others

Some of the modules also export types that can be used to define payloads for function calls. For example, the job exports JobTypes.

The job also exports a method to run a job.


Language support

Currently the client only supports JavaScript and TypeScript. But if you are looking to add support for other languages, message us in Discord and we can help you get started.


Usage in tests

To access the properties in your tests, you'll need to wrap your tests with the sst bind CLI.

sst bind -- vitest run

This allows the @serverless-stack/node package to work as if it was running inside a Lambda function.

Read more about testing and learn about the sst bind CLI.