Global

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

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

Note

The Global library is only 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

• protect

• providers

• removal

• stage

Context about the app being run.

$app.name

Type string

The name of the current app.

$app.protect

Type boolean

If true, prevents sst remove from being executed on this stage

$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. You can use this to conditionally deploy resources based on the stage.

For example, to deploy a bucket only in the dev stage:

sst.config.ts

if ($app.stage === "dev") {
  new sst.aws.Bucket("MyBucket");
}

$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

$asset

$asset(assetPath)

Parameters

• assetPath string

Returns FileArchive | FileAsset

Packages a file or directory into a Pulumi asset. This can be used for Pulumi resources that take an asset as input.

When the given path is a file, it returns a FileAsset. If the path is a directory, it returns a FileArchive with the zipped contents of the directory.

Tip

This automatically resolves paths relative to the root of the app.

Relative paths are resolved relative to the root of the app. While, absolute paths are used as is.

If you have a file inside the images directory at the root of your app, you can upload it to S3 on deploy.

sst.config.ts

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

new aws.s3.BucketObjectv2("MyImage", {
  bucket: bucket.name,
  key: "public/spongebob.svg",
  contentType: "image/svg+xml",
  source: $asset("images/spongebob.svg"),
});

You can also use this to zip up the files in the files/ directory and upload it to S3.

sst.config.ts

new aws.s3.BucketObjectv2("MyZip", {
  bucket: bucket.name,
  key: "public/spongebob.zip",
  contentType: "application/zip",
  source: $asset("files"),
});

$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:

sst.config.ts

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

Instead of having to resolve the bucket name first::

sst.config.ts

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

You can directly do this:

sst.config.ts

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:

sst.config.ts

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

Instead of resolving the bucket name first:

sst.config.ts

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

You can directly do this:

sst.config.ts

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:

sst.config.ts

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

You can directly do this:

sst.config.ts

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:

sst.config.ts

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

You can directly do this:

sst.config.ts

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:

sst.config.ts

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:

sst.config.ts

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

$transform

$transform(resource, cb)

Parameters

• resource Component Class

• cb (args, opts, name) => 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.

sst.config.ts

$transform(sst.aws.Function, (args, opts, name) => {
  // Set the default if it's not set by the component
  args.runtime ??= "nodejs20.x";
});

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

sst.config.ts

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

AWS

iamEdit

iamEdit(policy, cb)

Parameters

• policy Input<string | PolicyDocument>

• cb (doc: Object) => void

Returns Output<string>

A helper to modify the AWS IAM policy.

The IAM policy document is normally in the form of a JSON string. This helper decodes the string into a JSON object and passes it to the callback. Allowing you to modify the policy document in a type-safe way.

For example, this comes in handy when you are transforming the policy of a component.

sst.config.ts

new sst.aws.Bucket("MyBucket", {
  transform: {
    policy: (args) => {
      args.policy = sst.aws.iamEdit(args.policy, (policy) => {
        policy.Statement.push({
          Effect: "Allow",
          Action: "s3:PutObject",
          Principal: { Service: "ses.amazonaws.com" },
          Resource: $interpolate`arn:aws:s3:::${args.bucket}/*`,
        });
      });
    },
  },
});