Global

The Global library is a collection of $ functions and variables that are available in the run function, of your sst.config.ts.

Tip

You don’t need to import the Global library. It’s available in the run function of your sst.config.ts.

For example, you can get the name of your app in your app config using $app.name.

sst.config.ts

export default $config({
  // ...
  async run() {
    console.log($app.name);
  }
});

The variables contain the context of the app that’s being run. While the functions help you work with the Outputs of components.

---

Variables

$app

Type Object

• name

• providers

• removal

• stage

Context about the app being run.

$app.name

Type string

The name of the current app.

$app.providers

Type undefined | Record<string, any>

The providers currently being used in the app.

$app.removal

Type “remove” | “retain” | “retain-all”

The removal policy for the current stage. If removal was not set in the sst.config.ts, this will be return its default value, retain.

$app.stage

Type string

The stage currently being run.

$dev

Type boolean

Returns true if the app is running in sst dev.

$util

Type @pulumi/pulumi

A convenience reference to the the util module from Pulumi.

This is useful for working with components. You can use these without importing or installing the Pulumi SDK. For example, to create a new asset, you can:

sst.config.ts

const myFiles = new $util.asset.FileArchive("./path/to/files");

This is equivalent to doing:

sst.config.ts

import * as pulumi from "@pulumi/pulumi";

const myFiles = new pulumi.asset.FileArchive("./path/to/files");

Functions

$concat

$concat(params)

Parameters

• params any[]

Returns Output<string>

Takes a sequence of Output values or plain JavaScript values, stringifies each, and concatenates them into one final string.

This is takes care of resolving the Output values for you. Say you had a bucket:

const bucket = new sst.aws.Bucket("MyBucket");

Instead of having to resolve the bucket name first::

const description = bucket.name.apply(name =>
  "This is a bucket named ".concat(name)
);

You can directly do this:

const description = $concat("This is a bucket named ", bucket.name);

$interpolate

$interpolate(literals, placeholders)

Parameters

• literals TemplateStringsArray<>

• placeholders any[]

Returns Output<string>

Use string interpolation on Output values.

This is takes care of resolving the Output values for you. Say you had a bucket:

const bucket = new sst.aws.Bucket("MyBucket");

Instead of resolving the bucket name first:

const description = bucket.name.apply(name => `This is a bucket named ${name}`);

You can directly do this:

const description = $interpolate`This is a bucket named ${bucket.name}`;

$jsonParse

$jsonParse(text, reviver?)

Parameters

• text Input<string>

• reviver? JSON.parse reviver

Returns Output<any>

Takes an Output value or plain JavaScript value, uses JSON.parse on the resolved JSON string to turn it into a JSON object.

So for example, instead of doing of resolving the value first:

const policy = policyStr.apply((policy) =>
  JSON.parse(policy)
);

You can directly do this:

const policy = $jsonParse(policyStr);

$jsonStringify

$jsonStringify(obj, replacer?, space?)

Parameters

• obj any

• replacer? JSON.stringify replacer

• space? string | number

Returns Output<string>

Takes an Output value or plain JSON object, uses JSON.stringify on the resolved JSON object to turn it into a JSON string.

So for example, instead of doing of resolving the value first:

const policy = policyObj.apply((policy) =>
  JSON.stringify(policy)
);

You can directly do this:

const policy = $jsonStringify(policyObj);

$resolve

$resolve(val)

Parameters

• val Record<string, Input<T>>

Returns Output<Record<string, T>>

Wait for a list of Output values to be resolved, and then apply a function to their resolved values.

Say you had a couple of S3 Buckets:

const bucket1 = new sst.aws.Bucket("MyBucket1");
const bucket2 = new sst.aws.Bucket("MyBucket2");

You can run a function after both of them are resolved:

$resolve([bucket1.name, bucket2.name]).apply(([value1, value2]) =>
  console.log({ value1, value2 })
);

$transform

$transform(resource, cb)

Parameters

• resource Component Class

• cb (args, opts) => void

Returns void

Register a function that’ll be called when a component of the given type is about to be created. This is useful for setting global defaults for your components.

Note

This function is only called for components that are created after the function is registered.

The function takes the arguments and options that are being passed to the component, and can modify them.

For example, to set a default runtime for all function components.

$transform(sst.aws.Function, (args, opts) => {
  args.runtime = "nodejs18.x";
})

Here, args and opts are what you’d pass to the Function component. Recall the signature of the Function component:

new sst.aws.Function(name: string, args: FunctionArgs, opts?: pulumi.ComponentResourceOptions)