AWS StepLens

Visualize, navigate and lint AWS Step Functions definitions (ASL) directly in your editor. Supports YAML (Serverless Framework), raw JSON, and JSONata query language.

Features

Interactive Graph Preview

Open a live graph of your state machine with a single click on the ⊤ toolbar icon.

• Gradient service cards on every state — 36 official AWS icons (Lambda, DynamoDB, S3, SNS, Bedrock, Step Functions, …), coloured left panel matching the AWS brand palette, state name + service subtitle + meta line.
• Every state kind gets its own card style — Task (per-service gradient), Fail (red + ⚠ Catch), Succeed (green ✓), Pass (grey arrow), Wait (teal clock), Choice (amber diamond), Map (green dashed + iterator glyph), Parallel (indigo dashed + branch glyph).
• Corner pill badges surface metadata at a glance: ↺ Retry: N, ×N (Map concurrency, ×∞ for unlimited), ‖N (Parallel branches), ⏱ waitForTaskToken.
• State count badge on every tab — see how many states each graph contains at a glance.
• Click any node → jumps to the matching line in the editor.
• Move the cursor in the editor → the corresponding node lights up with a golden halo.
• Escape clears the current highlight; Cmd/Ctrl + −/+/0 zoom / fit.
• Double-click a Parallel or Map card → opens its sub-graph in a dedicated tab (works at any nesting depth).
• ← Main back button appears automatically when browsing a sub-graph.
• ⊡ Fit / − / + buttons recenter or step-zoom the graph.
• ▦ Catalog button opens a full-page overlay showing every card variant (one per AWS service + one per flow-control state + badge variants). Useful for exploring what the extension can render.
• ☀ / ☾ theme toggle — switch the graph background between dark and light; affects the live preview, JPEG export, and HTML export.
• ⬇ Export ▾ dropdown — export the current view as PNG, JPEG, or a fully self-contained interactive HTML file.
• Design Reference sidebar (right, 270 px) — gradient swatches per service family, badge legend, edge-type legend. Toggle via the ☰ Legend button.

Node annotations (badge overlay)

Export

The ⬇ Export ▾ dropdown in the graph toolbar offers three formats:

The graph is automatically refitted before PNG and JPEG capture. The HTML export is a fully self-contained file (Cytoscape and dagre bundled inline) — no internet connection required. Toggle ☀/☾ before exporting JPEG or HTML to choose the background.

Language features

Real-time Linter

50+ rules covering structural validity, JSONata/JSONPath field usage, distributed Map configuration, and state name constraints. Errors and warnings appear inline as you type, with hover tooltips explaining each issue. Every rule fires only on what can be determined from the ASL definition itself — no false positives from workflow-type assumptions.

Structural rules

JSONata rules (when QueryLanguage: JSONata)

Usage

1. Open any YAML or JSON file containing a Step Functions definition.
2. The ⊤ icon appears in the editor toolbar — click it to open the graph.
3. Lint errors appear as squiggly underlines; hover over them to read the message.
4. The status bar shows ✓ StepLens (clean), ⚠ N warnings, or ✗ N errors.

Icon not visible? The toolbar icon may be hidden behind the ··· overflow menu (three dots at the right of the editor title bar). Click ··· to find it, then right-click it to pin it to the toolbar.

Commands

You can also run StepLens commands from the Command Palette (⇧⌘P on macOS, Ctrl+Shift+P on Windows/Linux):

Settings

Setting changes apply immediately — disabling autoDetect clears all diagnostics at once; toggling lintOnType or lintOnSave re-lints all open files right away.

Supported formats

StepLens tolerates the CloudFormation intrinsic tags (!GetAtt, !Ref, !Sub, !Join, !If, !Split, !Select, !Base64, !ImportValue, and more) that Serverless Framework / SAM templates sprinkle around ASL definitions. They're registered as custom YAML tags so parsing stays silent — no TAG_RESOLVE_FAILED noise in the dev console.

Raw ASL (JSON)

{
  "Comment": "Document approval workflow",
  "StartAt": "SubmitDocument",
  "States": {
    "SubmitDocument": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:eu-west-1:123456789012:function:submit-doc",
      "Next": "ReviewDocument"
    },
    "ReviewDocument": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:eu-west-1:123456789012:function:review-doc",
      "End": true
    }
  }
}

Raw ASL with JSONata

{
  "Comment": "Order routing with JSONata",
  "QueryLanguage": "JSONata",
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:eu-west-1:123456789012:function:validate-order",
      "Arguments": {
        "orderId": "{% $states.input.id %}",
        "total":   "{% $states.input.price * $states.input.qty %}"
      },
      "Assign": { "orderType": "{% $states.input.type %}" },
      "Next": "RouteByType"
    },
    "RouteByType": {
      "Type": "Choice",
      "Choices": [
        { "Condition": "{% $orderType = 'express' %}",  "Next": "ExpressShipping" },
        { "Condition": "{% $orderType = 'standard' %}", "Next": "StandardShipping" }
      ],
      "Default": "FallbackRoute"
    },
    "ExpressShipping":  { "Type": "Task", "Resource": "arn:aws:lambda:eu-west-1:123456789012:function:express",  "End": true },
    "StandardShipping": { "Type": "Task", "Resource": "arn:aws:lambda:eu-west-1:123456789012:function:standard", "End": true },
    "FallbackRoute":    { "Type": "Fail", "Error": "UnknownType", "Cause": "Unrecognised order type" }
  }
}

Serverless Framework (YAML) — flat wrapper

definition:
  Comment: Document approval workflow
  StartAt: ReceiveDocument
  States:

    ReceiveDocument:
      Type: Task
      Resource: arn:aws:states:::lambda:invoke
      Next: WaitForReview

    WaitForReview:
      Type: Task
      Resource: arn:aws:states:::lambda:invoke.waitForTaskToken
      Parameters:
        FunctionName: request-review
        Payload:
          taskToken.$: $$.Task.Token
      HeartbeatSeconds: 3600
      Catch:
        - ErrorEquals: [States.HeartbeatTimeout]
          Next: ReviewTimedOut
      Next: CheckDecision

    CheckDecision:
      Type: Choice
      Choices:
        - Variable: $.decision
          StringEquals: approved
          Next: PublishDocument
        - Variable: $.decision
          StringEquals: rejected
          Next: RejectDocument
      Default: ReviewTimedOut

    PublishDocument:
      Type: Task
      Resource: arn:aws:states:::lambda:invoke
      Next: NotifyAuthor

    RejectDocument:
      Type: Task
      Resource: arn:aws:states:::lambda:invoke
      Next: NotifyAuthor

    NotifyAuthor:
      Type: Task
      Resource: arn:aws:states:::lambda:invoke
      End: true

    ReviewTimedOut:
      Type: Fail
      Error: ReviewTimeout
      Cause: No reviewer response within the deadline

Serverless Framework (YAML) — named wrapper

documentApproval:
  name: ${self:service}-${opt:stage}-doc-approval
  role: !GetAtt DocumentApprovalRole.Arn
  definition:
    Comment: Named Serverless Framework state machine
    StartAt: ReceiveDocument
    States:
      ReceiveDocument:
        Type: Task
        Resource: arn:aws:states:::lambda:invoke
        End: true

Parallel branches

definition:
  Comment: Enrich a user record with two parallel lookups
  StartAt: EnrichUser
  States:

    EnrichUser:
      Type: Parallel
      Branches:
        - StartAt: FetchLocation
          States:
            FetchLocation:
              Type: Task
              Resource: arn:aws:states:::lambda:invoke
              Parameters: { FunctionName: fetch-location, Payload.$: $ }
              End: true
        - StartAt: FetchPreferences
          States:
            FetchPreferences:
              Type: Task
              Resource: arn:aws:states:::lambda:invoke
              Parameters: { FunctionName: fetch-prefs, Payload.$: $ }
              End: true
      Next: MergeResults

    MergeResults:
      Type: Task
      Resource: arn:aws:states:::lambda:invoke
      End: true

Tip: Double-click the EnrichUser node in the graph to explore each branch in a dedicated tab. The node label shows ‖2 (2 branches).

SAM template with DefinitionUri

StepLens automatically resolves the local file referenced by DefinitionUri in AWS::Serverless::StateMachine resources — the linter, graph preview, and all commands work directly on the SAM template.

Resources:
  MyStateMachine:
    Type: AWS::Serverless::StateMachine
    Properties:
      DefinitionUri: statemachine/my_machine.asl.yaml
      Policies:
        - LambdaInvokePolicy:
            FunctionName: !Ref MyFunction

S3 DefinitionUri objects ({ Bucket, Key }) are not supported — only local file paths.

Map iterator

definition:
  Comment: Process a batch of uploaded files
  StartAt: ProcessFiles
  States:

    ProcessFiles:
      Type: Map
      ItemsPath: $.files
      MaxConcurrency: 5
      Iterator:
        StartAt: TranscodeFile
        States:
          TranscodeFile:
            Type: Task
            Resource: arn:aws:states:::lambda:invoke
            Parameters: { FunctionName: transcode, Payload.$: $ }
            Retry:
              - ErrorEquals: [States.TaskFailed]
                IntervalSeconds: 5
                MaxAttempts: 3
                BackoffRate: 2
            End: true
      Next: SaveManifest

    SaveManifest:
      Type: Task
      Resource: arn:aws:states:::lambda:invoke
      End: true

The ProcessFiles node label shows ×5 (MaxConcurrency) and TranscodeFile shows ↺ (Retry configured). A Parallel state with 3 branches would show ‖3.

Graph legend

Nodes

Edges

JSONata quick reference

When QueryLanguage: "JSONata" is set (globally or per-state):

JSONata expressions must be wrapped in {%…%}:

"Arguments": {
  "name":  "{% $states.input.user.name %}",
  "total": "{% $states.input.price * $states.input.qty %}",
  "id":    "{% $uuid() %}"
}

$states variable paths:

AWS-specific functions: $partition(), $range(), $hash(), $random(), $uuid(), $parse()

$eval() is not supported by AWS Step Functions.

License

MIT