StepFunctions

The StepFunctions component lets you add state machines to your app using AWS Step Functions.

You define your state machine using a collection of states. Where each state needs a unique name. It uses JSONata for transforming data between states.

Minimal example

The state machine definition is compiled into JSON and passed to AWS.

const foo = sst.aws.StepFunctions.pass({ name: "Foo" });
const bar = sst.aws.StepFunctions.succeed({ name: "Bar" });

const definition = foo.next(bar);

new sst.aws.StepFunctions("MyStateMachine", {
  definition
});

Invoking a Lambda function

Create a function and invoke it from a state machine.

const myFunction = new sst.aws.Function("MyFunction", {
  handler: "src/index.handler"
});

const invoke = sst.aws.StepFunctions.lambdaInvoke({
  name: "InvokeMyFunction",
  function: myFunction
});
const done = sst.aws.StepFunctions.succeed({ name: "Done" });

new sst.aws.StepFunctions("MyStateMachine", {
  definition: invoke.next(done)
});

Use the express workflow

const foo = sst.aws.StepFunctions.pass({ name: "Foo" });
const bar = sst.aws.StepFunctions.succeed({ name: "Bar" });

new sst.aws.StepFunctions("MyStateMachine", {
  type: "express",
  definition: foo.next(bar)
});

Constructor

new StepFunctions(name, args, opts?)

Parameters

name string
args StepFunctionsArgs
opts? ComponentResourceOptions

StepFunctionsArgs

definition

Type State

The definition of the state machine. It takes a chain of State objects.

const foo = sst.aws.StepFunctions.pass({ name: "Foo" });
const bar = sst.aws.StepFunctions.succeed({ name: "Bar" });

new sst.aws.StepFunctions("MyStateMachine", {
  definition: foo.next(bar)
});

logging?

Type Input<false | Object>

includeData?
level?
retention?

Default {retention: “1 month”, level: “error”, includeData: false}

Configure the execution logs in CloudWatch. Or pass in false to disable writing logs.

{
  logging: false
}

logging.includeData?

Type Input<boolean>

Default false

Specify whether execution data is included in the logs.

{
  logging: {
    includeData: true
  }
}

logging.level?

Type Input<“all” | “error” | “fatal”>

Default “error”

Specify the type of execution events that are logged. Read more about the Step Functions log level.

{
  logging: {
    level: "all"
  }
}

Default 1 month

The duration the logs are kept in CloudWatch.

{
  logging: {
    retention: "forever"
  }
}

transform?

Type Object

logGroup?
stateMachine?

Transform how this component creates its underlying resources.

transform.logGroup?

Type LogGroupArgs | (args: LogGroupArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Step Functions LogGroup resource.

transform.stateMachine?

Type StateMachineArgs | (args: StateMachineArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Step Functions StateMachine resource.

type?

Type Input<“standard” | “express”>

Default “standard”

The type of state machine workflow to create.

The standard workflow is the default and is meant for long running workflows. The express workflow is meant for workflows shorter than 5 minutes.

This is because the express workflow is run in a single Lambda function. As a result, it’s faster and cheaper to run. So if your workflow are short, the express workflow is recommended.

{
  type: "express"
}

Properties

arn

Type Output<string>

The State Machine ARN.

nodes

Type Object

stateMachine

The underlying resources this component creates.

nodes.stateMachine

Type StateMachine

The Step Function State Machine resource.

SDK

Use the SDK in your runtime to interact with your infrastructure.

Methods

static choice

StepFunctions.choice(args)

Parameters

args ChoiceArgs

Returns Choice

A Choice state is used to conditionally continue to different states based on the matched condition.

const processPayment = sst.aws.StepFunctions.choice({ name: "ProcessPayment" });

const makePayment = sst.aws.StepFunctions.lambdaInvoke({ name: "MakePayment" });
const sendReceipt = sst.aws.StepFunctions.lambdaInvoke({ name: "SendReceipt" });
const failure = sst.aws.StepFunctions.fail({ name: "Failure" });

processPayment.when("{% $states.input.status === 'unpaid' %}", makePayment);
processPayment.when("{% $states.input.status === 'paid' %}", sendReceipt);
processPayment.otherwise(failure);

static fail

StepFunctions.fail(args)

Parameters

args FailArgs

Returns Fail

A Fail state is used to fail the execution of a state machine.

sst.aws.StepFunctions.fail({ name: "Failure" });

static map

StepFunctions.map(args)

Parameters

args MapArgs

Returns Map

A Map state is used to iterate over a list of items and execute a task for each item.

const processor = sst.aws.StepFunctions.lambdaInvoke({
  name: "Processor",
  function: "src/processor.handler"
});

sst.aws.StepFunctions.map({
  processor,
  name: "Map",
  items: "{% $states.input.items %}"
});

static parallel

StepFunctions.parallel(args)

Parameters

args ParallelArgs

Returns Parallel

A Parallel state is used to execute multiple branches of a state in parallel.

const processorA = sst.aws.StepFunctions.lambdaInvoke({
  name: "ProcessorA",
  function: "src/processorA.handler"
});

const processorB = sst.aws.StepFunctions.lambdaInvoke({
  name: "ProcessorB",
  function: "src/processorB.handler"
});

const parallel = sst.aws.StepFunctions.parallel({ name: "Parallel" });

parallel.branch(processorA);
parallel.branch(processorB);

static pass

StepFunctions.pass(args)

Parameters

args PassArgs

Returns Pass

A Pass state is used to pass the input to the next state. It’s useful for transforming the input before passing it along.

sst.aws.StepFunctions.pass({
  name: "Pass",
  output: "{% $states.input.message %}"
});

static succeed

StepFunctions.succeed(args)

Parameters

args SucceedArgs

Returns Succeed

A Succeed state is used to indicate that the execution of a state machine has succeeded.

sst.aws.StepFunctions.succeed({ name: "Succeed" });

static task

StepFunctions.task(args)

Parameters

args TaskArgs

Returns Task

A Task state can be used to make calls to AWS resources. We created a few convenience methods for common tasks like:

sst.aws.StepFunctions.lambdaInvoke to invoke a Lambda function.
sst.aws.StepFunctions.ecsRunTask to run an ECS task.
sst.aws.StepFunctions.eventBridgePutEvents to send custom events to EventBridge.

For everything else, you can use the Task state.

For example, to start an AWS CodeBuild build.

sst.aws.StepFunctions.task({
  name: "Task",
  resource: "arn:aws:states:::codebuild:startBuild",
  arguments: {
    projectName: "my-codebuild-project"
  },
  permissions: [
    {
      actions: ["codebuild:StartBuild"],
      resources: ["*"]
    }
  ]
});

static wait

StepFunctions.wait(args)

Parameters

args WaitArgs

Returns Wait

A Wait state is used to wait for a specific amount of time before continuing to the next state.

For example, wait for 10 seconds before continuing to the next state.

sst.aws.StepFunctions.wait({
  name: "Wait",
  time: 10
});

Alternatively, you can wait until a specific timestamp.

sst.aws.StepFunctions.wait({
  name: "Wait",
  timestamp: "2026-01-01T00:00:00Z"
});

static ecsRunTask

StepFunctions.ecsRunTask(args)

Parameters

args EcsRunTaskArgs

Returns Task

Create a Task state that runs an ECS task using the Task component. Learn more.

const myCluster = new sst.aws.Cluster("MyCluster");
const myTask = new sst.aws.Task("MyTask", { cluster: myCluster });

sst.aws.StepFunctions.ecsRunTask({
  name: "RunTask",
  task: myTask
});

static eventBridgePutEvents

StepFunctions.eventBridgePutEvents(args)

Parameters

args EventBridgePutEventsArgs

Returns Task

Create a Task state that sends custom events to one or more EventBridge buses using the Bus component. Learn more.

const myBus = new sst.aws.EventBus("MyBus");

sst.aws.StepFunctions.eventBridgePutEvents({
  name: "EventBridgePutEvents",
  events: [
    {
      bus: myBus,
      source: "my-source"
    }
  ]
});

static lambdaInvoke

StepFunctions.lambdaInvoke(args)

Parameters

args LambdaInvokeArgs

Returns Task

Create a Task state that invokes a Lambda function. Learn more.

sst.aws.StepFunctions.lambdaInvoke({
  name: "LambdaInvoke",
  function: "src/index.handler"
});

Customize the function.

sst.aws.StepFunctions.lambdaInvoke({
  name: "LambdaInvoke",
  function: {
    handler: "src/index.handler"
    timeout: "60 seconds",
  }
});

Pass in an existing Function component.

const myLambda = new sst.aws.Function("MyLambda", {
  handler: "src/index.handler"
});

sst.aws.StepFunctions.lambdaInvoke({
  name: "LambdaInvoke",
  function: myLambda
});

Or pass in the ARN of an existing Lambda function.

sst.aws.StepFunctions.lambdaInvoke({
  name: "LambdaInvoke",
  function: "arn:aws:lambda:us-east-1:123456789012:function:my-function"
});

static snsPublish

StepFunctions.snsPublish(args)

Parameters

args SnsPublishArgs

Returns Task

Create a Task state that publishes a message to an SNS topic. Learn more.

const myTopic = new sst.aws.SnsTopic("MyTopic");

sst.aws.StepFunctions.snsPublish({
  name: "SnsPublish",
  topic: myTopic,
  message: "Hello, world!"
});

static sqsSendMessage

StepFunctions.sqsSendMessage(args)

Parameters

args SqsSendMessageArgs

Returns Task

Create a Task state that sends a message to an SQS queue. Learn more.

const myQueue = new sst.aws.Queue("MyQueue");

sst.aws.StepFunctions.sqsSendMessage({
  name: "SqsSendMessage",
  queue: myQueue,
  messageBody: "Hello, world!"
});