{"id":17673626,"url":"https://github.com/codetheweb/serverless-step-functions-local","last_synced_at":"2025-10-28T11:31:18.233Z","repository":{"id":34932801,"uuid":"313350969","full_name":"codetheweb/serverless-step-functions-local","owner":"codetheweb","description":"Run AWS step functions offline with Serverless ","archived":false,"fork":false,"pushed_at":"2024-08-12T10:55:02.000Z","size":184,"stargazers_count":17,"open_issues_count":7,"forks_count":18,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-05T22:15:39.028Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codetheweb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-16T15:47:24.000Z","updated_at":"2024-10-04T18:43:27.000Z","dependencies_parsed_at":"2023-01-15T10:41:05.722Z","dependency_job_id":"b6dbc44c-f0e2-46be-853e-ca00e946a61e","html_url":"https://github.com/codetheweb/serverless-step-functions-local","commit_stats":{"total_commits":43,"total_committers":12,"mean_commits":"3.5833333333333335","dds":0.7441860465116279,"last_synced_commit":"5548f237f81664d1d723ca4acd1631a5c84cd215"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codetheweb%2Fserverless-step-functions-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codetheweb%2Fserverless-step-functions-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codetheweb%2Fserverless-step-functions-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codetheweb%2Fserverless-step-functions-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codetheweb","download_url":"https://codeload.github.com/codetheweb/serverless-step-functions-local/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238642381,"owners_count":19506200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-24T05:42:40.102Z","updated_at":"2025-10-28T11:31:17.839Z","avatar_url":"https://github.com/codetheweb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# serverless-step-functions-local\nRun AWS step functions offline with Serverless!\n\nThis is a plugin for the [Serverless Framework](https://serverless.com/).  It uses [stepfunctions-localhost](https://www.npmjs.com/package/stepfunctions-localhost) to emulate step functions with AWS' provided tool for local development.\n\n## Requirements\n\n- serverless \u003e= v3.0.0\n- The [serverless-offline](https://www.npmjs.com/package/serverless-offline) plugin\n- The [serverless-offline-lambda](https://www.npmjs.com/package/serverless-offline-lambda) plugin\n- The [serverless-step-functions](https://www.npmjs.com/package/serverless-step-functions) plugin\n- Java Runtime Engine (JRE) version 6.x or newer\n\n## Install\n\n`npm install serverless-step-functions-local -D`\n\n## Getting Started\n\nYou'll need to add this plugin to your `serverless.yml`.  The plugins section should look something like this when you're done:\n\n```yaml\nplugins:\n  ...\n  - serverless-step-functions\n  - serverless-step-functions-local\n  - serverless-offline-lambda\n  - serverless-offline\n  ...\n```\n\nThen, add a new section to `config` with `accountId` and `region` parameters:\n\n```yaml\ncustom:\n  stepFunctionsLocal:\n    accountId: 101010101010\n    region: us-east-1\n```\n\nAlthough not neccessary, it's strongly recomended to add the folder with the downloaded step function executables to `.gitignore`.  By default, this path is `./.step-functions-local`.\n\nThe plugin binds to port 8083, this cannot be changed.\nThe plugin binds to port 8083, since [stepfunctions-localhost](https://www.npmjs.com/package/stepfunctions-localhost) doesn't support dynamic port, it can't be changed.\n\nIt also adds an environment variable for each created state machine that contains the ARN for it.  These variables are prefixed by `OFFLINE_STEP_FUNCTIONS_ARN_`, so the ARN of a state machine named 'WaitMachine', for example could be fetched by reading `OFFLINE_STEP_FUNCTIONS_ARN_WaitMachine`.\n\n## Options\n\n(These go under `custom.stepFunctionsLocal`.)\n\n- `accountId` (required) your AWS account ID\n- `region` (required) your AWS region\n- `lambdaEndpoint` (defaults to `http://localhost:3000` from serverless offline) the endpoint for the lambda service. This plugin tries to use the configured value from serverless-offline\n- `path` (defaults to `./.step-functions-local`) the path to store the downloaded step function executables\n- `TaskResourceMapping` allows for Resource ARNs to be configured differently for local development. (Serverless 3.x prefixes the lambda function names with the stack name and the stage)\n- `eventBridgeEvents` allows sending [EventBridge events](https://docs.aws.amazon.com/step-functions/latest/dg/cw-events.html) on execution status changes\n  - `enabled` (bool) enabled or disable this feature. Disabled by default.\n  - `endpoint` Endpoint for sending events to eg. for [serverless-offline-aws-eventbridge](https://github.com/rubenkaiser/serverless-offline-eventBridge) would be `http://localhost:4010`\n- `externalInstance` allows to set a flag to use external instance of local step functions. Disabled by default.\n- `stepFunctionsEndpoint` (defaults to `http://localhost:8083`) the endpoint for the step functions service\n### Full Config Example\n\n```yaml\nservice: local-step-function\n\nplugins:\n  - serverless-step-functions\n  - serverless-step-functions-local\n  - serverless-offline-lambda\n  - serverless-offline\n\nprovider:\n  name: aws\n  runtime: nodejs14.x # supported nodejs versions: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html\n\n\ncustom:\n  stepFunctionsLocal:\n    accountId: 101010101010\n    region: us-east-1\n    TaskResourceMapping:\n      FirstState: arn:aws:lambda:us-east-1:101010101010:function:${self:service}-${opt:stage, self:provider.stage}-hello\n      FinalState: arn:aws:lambda:us-east-1:101010101010:function:${self:service}-${opt:stage, self:provider.stage}-hello\n    eventBridgeEvents:\n      enabled: true\n      endpoint: http://localhost:4010\n  sqsUrl: http://localhost:4566/101010101010/example-queue\n\nfunctions:\n  hello:\n    handler: handler.hello\n\nstepFunctions:\n  stateMachines:\n    WaitMachine:\n      definition:\n        Comment: \"An example of the Amazon States Language using wait states\"\n        StartAt: FirstState\n        States:\n          FirstState:\n            Type: Task\n            Resource: Fn::GetAtt: [hello, Arn]\n            Next: send_message\n          send_message:\n            Type: Task\n            Resource: arn:aws:states:::sqs:sendMessage\n            Parameters:\n              QueueUrl: ${self:custom.sqsUrl}\n              \"MessageBody.$\": \"$\"\n            Next: wait_using_seconds\n          wait_using_seconds:\n            Type: Wait\n            Seconds: 10\n            Next: FinalState\n          FinalState:\n            Type: Task\n            Resource: Fn::GetAtt: [hello, Arn]\n            End: true\n```\n\n## Start your local step functions\n\nTo run your local step function, use this command:\n\n```\naws stepfunctions --endpoint-url http://localhost:8083 start-execution --state-machine-arn arn:aws:states:us-east-1:101010101010:stateMachine:servicename-stagename-hello --input '{\"hello\": [\"world\"]}'\n```\n\n## Running external instance\n\nTo run external step functions local using docker, use this command:\n\n```\ndocker run \\\n    -p 8083:8083 \\\n    -e \"AWS_ACCOUNT_ID=101010101010\" \\\n    -e \"AWS_DEFAULT_REGION=us-east-1\" \\\n    -e \"LAMBDA_ENDPOINT=http://localhost:4000\" \\\n    amazon/aws-stepfunctions-local\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodetheweb%2Fserverless-step-functions-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodetheweb%2Fserverless-step-functions-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodetheweb%2Fserverless-step-functions-local/lists"}