Registry / aws / serverless-step-functions

serverless-step-functions

library3.29.1jsnpmunverified

The `serverless-step-functions` plugin provides deep integration for AWS Step Functions within the Serverless Framework. It allows developers to define, deploy, and manage complex serverless workflows directly within their `serverless.yml` configuration. As of version `3.29.1`, the project maintains a rapid release cadence, frequently pushing out new features and bug fixes, often several times per month. Key differentiators include automatic IAM role generation tailored to state machine definitions, comprehensive event source integrations (such as API Gateway, Scheduled events, and CloudWatch Events), support for advanced features like Blue-Green deployments, pre-deployment validation, CloudWatch Alarms, and X-Ray tracing. It significantly streamlines the orchestration of AWS services by abstracting away much of the underlying CloudFormation complexity required for Step Functions.

aws devops workflow

npm install serverless-step-functions

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SERVERLESS-STEP-FU

serverless-step-functions

awsjavascriptv3.29.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

serverless-step-functions (plugin declaration)

✓ plugins: - serverless-step-functions

The plugin is enabled by listing its name under the `plugins` section of your `serverless.yml`. This is the primary 'import' mechanism for Serverless plugins.

stateMachines (configuration block)

✓ stepFunctions: stateMachines: myStateMachine: definition: Comment: "A simple state machine" StartAt: "Hello" States: Hello: Type: Pass End: true

✗ # Incorrect placement, will not be recognized by the plugin: stateMachines: myStateMachine: # ...

State machines are defined under the `stepFunctions.stateMachines` property in `serverless.yml`. Incorrect placement or YAML syntax errors are common mistakes.

httpApi event trigger

✓ stepFunctions: stateMachines: myApiStateMachine: definition: Comment: "A state machine triggered by API Gateway" StartAt: "Hello" States: Hello: Type: Pass End: true events: - httpApi: path: /my-workflow method: post async: true response: headers: Content-Type: "'application/json'" template: "$input.json('$')"

✗ # Incorrect if you want direct Step Functions integration. This would create a Lambda proxy: functions: myApiTriggerLambda: handler: handler.myApiTrigger events: - httpApi: path: /my-workflow method: post

API Gateway events can directly integrate with Step Functions, allowing an HTTP endpoint to start a workflow. Ensure `async: true` and the event is defined *within the state machine's `events` block* to achieve direct asynchronous invocation. Defining it under `functions` creates a Lambda proxy.

This `serverless.yml` configuration demonstrates how to define a simple AWS Step Functions state machine with a basic `Wait` and `Succeed` state. It also shows how to trigger this workflow asynchronously via an AWS HTTP API endpoint, configuring the necessary API Gateway integration. This configuration should be placed in your `serverless.yml` file and deployed using `sls deploy`.

# serverless.yml service: my-step-functions-service frameworkVersion: '3' plugins: - serverless-step-functions provider: name: aws runtime: nodejs20.x # Or any supported runtime region: us-east-1 stage: dev httpApi: cors: true stepFunctions: stateMachines: mySimpleWorkflow: name: my-simple-workflow-${sls:stage} comment: "A basic workflow that waits and then succeeds" definition: Comment: "My Simple Workflow" StartAt: "WaitState" States: WaitState: Type: Wait Seconds: 5 Next: "SucceedState" SucceedState: Type: Succeed events: - httpApi: path: /start-workflow method: post async: true response: headers: Content-Type: "'application/json'" template: "$input.json('$')"

Debug

Known issues

breakingVersion 3.x of `serverless-step-functions` requires Serverless Framework `v3.0.0` or later. Deployments with older Serverless Framework versions will fail.

fix

Upgrade your Serverless Framework CLI and project configuration to `v3.0.0` or newer. Run `npm install -g serverless@latest` or `npm install serverless@latest` in your project.

affects: >=3.0.0

breakingAs of recent versions (specifically aligning with Serverless Framework v3.x), the plugin requires Node.js version `22` or higher. Older Node.js versions will result in deployment failures.

fix

Ensure your development environment and deployment environment (if running local `sls deploy`) use Node.js version 22 or newer. Consider using `nvm` to manage Node.js versions.

affects: >=3.0.0

gotchaWhile the plugin aims to auto-generate correct IAM permissions, complex state machine definitions or custom service integrations may still require manual augmentation of IAM roles to prevent permission denied errors during execution.

fix

Carefully review the CloudFormation generated IAM policies and add any missing permissions under the `iamRoleStatements` section in your `serverless.yml` or the `custom` section of the plugin configuration.

affects: >=3.0.0

gotchaWhen using `Fn::Sub` expressions within a Lambda resource ARN for state machine definitions, ensure proper nesting and escaping. Improperly nested `Fn::Sub` can lead to deployment or runtime errors.

fix

Avoid deeply nested `Fn::Sub` within Lambda resource references if possible. If necessary, use `Fn::Join` or define the ARN as a separate CloudFormation resource/variable for clarity and to prevent improper parsing.

affects: >=3.0.0

gotchaWhen defining API Gateway `apiKeys`, ensure you use the object form, especially for more complex configurations. Earlier versions might have had issues with simpler string arrays for `apiKeys`.

fix

Always define `apiKeys` as an array of objects, e.g., `- { name: 'my-api-key', value: '...' }` instead of just string names, to ensure compatibility and full feature support.

affects: >=3.28.1

Errors

Common errors & fixes

Serverless Framework Error: This plugin is not compatible with your version of the Serverless Framework. Please use 'serverless@3.x.x'.

The installed `serverless-step-functions` plugin requires Serverless Framework `v3.0.0` or higher, but an older version is in use.

fix

Upgrade the Serverless Framework CLI: `npm install -g serverless@latest` and ensure your project's `package.json` specifies `serverless` v3 or greater.

The CloudFormation template is invalid: Template format error: YAML not well-formed

There's a syntax error or incorrect indentation in your `serverless.yml` configuration for the Step Functions plugin.

fix

Carefully review your `serverless.yml` for correct YAML syntax, especially indentation, dashes for lists, and proper key-value pairs. Use a YAML linter or IDE support for validation.

AccessDeniedException: User: arn:aws:iam::... is not authorized to perform: states:StartExecution on resource: arn:aws:states:...

The IAM role assigned to your API Gateway or other event source does not have the necessary permissions to start the Step Functions state machine execution.

fix

Add `states:StartExecution` permission for the specific state machine ARN to the IAM role that triggers the workflow. This might be a `iamRoleStatements` entry in your `serverless.yml` provider section or a custom role defined for the event.

InvalidArn: The state machine ARN is not valid.

The ARN for a referenced state machine or a related AWS resource in your configuration is incorrectly formatted or points to a non-existent resource.

fix

Verify that any ARNs specified in your state machine definition or event configurations are correct and that the resources they refer to exist and are deployed in the same region/account. Ensure any Serverless variables (e.g., `${self:provider.region}`) are correctly resolved.

Upgrade

Version history

3.29.1latest on npm

Audit

Dependencies

serverlessrequiredPeer dependency for core framework functionality; plugin requires a compatible Serverless Framework version.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/serverless-operations/serverless-step-functions ↗

packagehttps://www.npmjs.com/package/serverless-step-functions ↗

homepagehttps://www.serverless.com ↗