AWS Step Cloner

aws-step-cloner is a Node.js utility that lets you download, clone, and re-upload AWS Step Functions along with all their corresponding AWS Lambda functions — in just a few lines of code.

It’s designed to make migrating, replicating, or backing up AWS workflows fast and seamless.

📦 Installation

Install via npm:

npm install aws-step-cloner

or via yarn:

yarn add aws-step-cloner

⚙️ Features

• Download Step Functions along with all referenced Lambda functions
• Upload cloned Step Functions with new Lambda ARNs
• One-click workflow duplication across AWS regions or accounts
• Automatic ARN mapping — no manual edits required
• Lightweight, dependency-efficient, and easy to integrate

🔑 Prerequisites

Before using the library, ensure you have:

An AWS IAM User or Role with the following permissions: 1. states 2. lambda: 3. iam:PassRole A valid StepFunctionRole and LambdaExecutionRole AWS credentials (Access Key & Secret Key)

1. Using the Downloader Class

The Downloader class helps you download an existing AWS Step Function along with all its Lambda functions to a local directory.

Example:

import { Downloader } from "aws-step-cloner";

const downloader = new Downloader();

const response = await downloader.download({
  accessKeyId: "<YOUR_AWS_ACCESS_KEY_ID>",
  secretAccessKey: "<YOUR_AWS_SECRET_ACCESS_KEY>",
  region: "ap-south-1",
  stateMachineArn: "arn:aws:states:ap-south-1:<YOUR_ACCOUNT_ID>:stateMachine:MySampleMachine",
  outputDir: "./south-downloaded",
});

Output: A new folder south-downloaded will be created containing:

• definition.json → the Step Function definition schema
• .zip files → code for all Lambda functions used in the workflow

2. Using the Uploader Class

The Uploader class allows you to recreate Step Functions and Lambda functions from a previously downloaded schema.

It automatically updates Lambda ARNs in the Step Function definition and creates a new Step Function.

Example:

import { Uploader } from "aws-step-cloner";

const uploader = new Uploader();

const uploadResponse = await uploader.upload({
  accessKeyId: "<YOUR_AWS_ACCESS_KEY_ID>",
  secretAccessKey: "<YOUR_AWS_SECRET_ACCESS_KEY>",
  region: "ap-south-1",
  stateMachineName: "MySampleMachine",
  definition: response.definition,
  roleArn: "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/StepFunctionRole",
  lambdaDir: "./south-downloaded",
  lambdaExecutionRoleArn: "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/LambdaExecutionRole",
  prefix: "clone-",
  stepFunctionDefinitionPath: response.definition,
  stepFunctionName: "MyStepFunctionClone",
});

Notes:

• The prefix is added to cloned resource names to avoid conflicts.
• Make sure your roles (StepFunctionRole, LambdaExecutionRole) have the correct permissions.
• You can reuse the folder generated by the Downloader.

3. Environment Variables Handling

AWS Step Cloner supports two ways of managing Lambda environment variables:

a) Use existing environment variables (envIncluded)

• If you want to reuse the environment variables fetched during download:

const uploadResponse = await uploader.upload({
  ...
  envIncluded: true, // Use previously downloaded env variables
});

b) Use a custom environment JSON file (envFilePath)

Provide a JSON file with environment variables for each Lambda:

{
  "Myfirst": {
    "DB_URI": "asdadsadasdadsda",
    "Key": "adsadasdadad",
    "Secret": "adsadasdadad",
    "db": "mydatabase",
    "port": 5432,
    "host": "localhost"

  },
  "MySecond": {
    "DB_URI": "sadsadasdasd",
    "key": "adsadadasds",
    "Secret": "adsadasdadad",
    "db": "mydatabase",
    "port": 5432,
    "host": "localhost"
  }
}

Noted: If you don't pass any option then the functions will create with no environment variables

Combined Usage (Recommended)

You can use both classes in a single script to download and re-upload a Step Function and its Lambdas in one go.

Example:

import { Downloader, Uploader } from "aws-step-cloner";

// Step 1: Download
const downloader = new Downloader();
const response = await downloader.download({
  accessKeyId: "<YOUR_AWS_ACCESS_KEY_ID>",
  secretAccessKey: "<YOUR_AWS_SECRET_ACCESS_KEY>",
  region: "ap-south-1",
  stateMachineArn: "arn:aws:states:ap-south-1:<YOUR_ACCOUNT_ID>:stateMachine:MySampleMachine",
  outputDir: "./south-downloaded",
});

// Step 2: Upload
const uploader = new Uploader();
const uploadResponse = await uploader.upload({
  accessKeyId: "<YOUR_AWS_ACCESS_KEY_ID>",
  secretAccessKey: "<YOUR_AWS_SECRET_ACCESS_KEY>",
  region: "ap-south-1",
  stateMachineName: "MySampleMachine",
  definition: response.definition,
  roleArn: "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/StepFunctionRole",
  lambdaDir: "./south-downloaded",
  lambdaExecutionRoleArn: "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/LambdaExecutionRole",
  prefix: "clone-",
  stepFunctionDefinitionPath: response.definition,
  stepFunctionName: "MyStepFunctionClone",
});

Example Output:

--- Downloaded Step Function definition
--- Downloaded Lambdas: [MyLambdaOne, MyLambdaTwo]
--- Created Lambdas: clone-MyLambdaOne, clone-MyLambdaTwo
--- Created Step Function: arn:aws:states:ap-south-1:123456789012:stateMachine:clone-MyStepFunctionClone
--- Clone completed successfully!

How It Works

Downloader

• Calls AWS Step Functions API to fetch the state machine definition.
• Scans the definition for Lambda ARNs.
• Downloads each Lambda code as a .zip file.
• Saves all files locally.

Uploader

• Reads downloaded .zip Lambda files.
• Creates new Lambda functions.
• Updates the Step Function definition with the new ARNs.
• Deploys a new Step Function.

Common Issues

| Problem | Cause | Solution | | -------------------------------------------- | --------------------------------------- | ------------------------------------------------ | | AccessDeniedException: iam:PassRole | IAM user lacks role-passing permission | Attach policy with "Action": "iam:PassRole" | | The "path" argument must be of type string | Passed an object instead of string path | Use actual JSON file path, not parsed object | | ResourceConflictException | Duplicate Step Function name | Use a unique prefix for cloning (e.g., clone-) |

License

This project is dual-licensed under either:

• MIT License
• Apache License 2.0

Author

Developed with ❤️ by Syed Bakhtawar Fahim

Software Engineer | Backend & Cloud

Support

If you found this package helpful:

• Star ⭐ the repository
• Contribute via pull requests
• Share your feedback and feature ideas