sfn-diagram

https://github.com/yusufaf/sfn-diagram
Admin
TypeScript library and CLI that renders AWS Step Functions state machines (ASL definitions,...
Tokens:89,980
Snippets:465
Trust Score:7.5
License:MIT
Update:5 days ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- AGENTS.md lists every entry point, its runtime and the common mistakes; check it before importing from a subpath.
- Functions take a single flat object parameter: options sit beside aslDefinition, e.g. generateSvg({ aslDefinition, layout: 'LR', theme: 'dark' }), never under an options key.
- Runtimes: 'sfn-diagram', 'sfn-diagram/cfn' and 'sfn-diagram/terraform' run in Node, browsers and edge. 'sfn-diagram/png' (exportPng), 'sfn-diagram/aws', 'sfn-diagram/ci' and the CLI are Node-only. 'sfn-diagram/element' is browser-only.
- generateFromAwsResponse is exported from the root 'sfn-diagram' entry, not from 'sfn-diagram/aws'.
- The extractors return an object: const { aslDefinition } = extractAslFromTemplate({ template }) from 'sfn-diagram/cfn', or extractAslFromTerraform({ config }) from 'sfn-diagram/terraform'.
- When a template or Terraform config defines more than one state machine, also pass resourceId: the CloudFormation logical ID, or the Terraform resource name (e.g. aws_sfn_state_machine.orders).

================
CODE SNIPPETS
================
### Run the playground locally with pnpm

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/ecosystem/playground.md

Install dependencies, build the library, and start the site dev server. The editor is then served at /playground.

```bash
pnpm install
pnpm run build          # build the library the playground imports
pnpm --filter sfn-diagram-site dev
```

--------------------------------

### Install sfn-diagram with bun

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/installation.mdx

Installs the core sfn-diagram package using bun.

```bash
bun add sfn-diagram
```

--------------------------------

### Install sfn-diagram-react with bun

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/ecosystem/react.mdx

Install the sfn-diagram-react package along with sfn-diagram and react using bun.

```bash
bun add sfn-diagram-react sfn-diagram react
```

--------------------------------

### Install sfn-diagram-react with npm

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/ecosystem/react.mdx

Install the sfn-diagram-react package along with sfn-diagram and react using npm.

```bash
npm install sfn-diagram-react sfn-diagram react
```

--------------------------------

### Install sfn-diagram-react with pnpm

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/ecosystem/react.mdx

Install the sfn-diagram-react package along with sfn-diagram and react using pnpm.

```bash
pnpm add sfn-diagram-react sfn-diagram react
```

--------------------------------

### Install sfn-diagram and @resvg/resvg-js with bun

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/installation.mdx

Installs sfn-diagram along with the optional peer dependency @resvg/resvg-js for PNG export.

```bash
bun add sfn-diagram @resvg/resvg-js
```

--------------------------------

### Install sfn-diagram-react with yarn

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/ecosystem/react.mdx

Install the sfn-diagram-react package along with sfn-diagram and react using yarn.

```bash
yarn add sfn-diagram-react sfn-diagram react
```

--------------------------------

### Install standalone binary with Homebrew

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Install the sfn-diagram standalone binary using Homebrew, or download the binary from a core release and make it executable with chmod +x.

```bash
brew install yusufaf/tap/sfn-diagram
# or download sfn-diagram-<os>-<arch> from a core release and chmod +x it
```

--------------------------------

### Install sfn-diagram and @resvg/resvg-js with pnpm

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/installation.mdx

Installs sfn-diagram along with the optional peer dependency @resvg/resvg-js for PNG export.

```bash
pnpm add sfn-diagram @resvg/resvg-js
```

--------------------------------

### Install sfn-diagram with yarn

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/installation.mdx

Installs the core sfn-diagram package using yarn.

```bash
yarn add sfn-diagram
```

--------------------------------

### Example sfn-diagram.config.json

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

A sample configuration file showing layout, icons, padding, and theme settings.

```json
{
  "layout": "LR",
  "showIcons": true,
  "padding": 40,
  "theme": { "base": "dark", "background": "#101014" }
}
```

--------------------------------

### Install sfn-diagram with pnpm

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/installation.mdx

Installs the core sfn-diagram package using pnpm.

```bash
pnpm add sfn-diagram
```

--------------------------------

### Following output example

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Example output while following an execution, showing polling every 2 seconds and the final success message.

```text
following arn:aws:states:us-east-1:111122223333:execution:Orders:run-1 every 2s (Ctrl-C to stop)
...
arn:aws:states:us-east-1:111122223333:execution:Orders:run-1 succeeded after 14 update(s)
```

--------------------------------

### Output of sfn-diagram --watch

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Example output from the --watch command, showing the initial message and change notifications. The output indicates that watching has started and lists changed files.

```text
watching 2 path(s); Ctrl-C to stop
  machines/order.asl.json changed
  machines/payments.asl.json changed
stopped watching
```

--------------------------------

### Install sfn-diagram via Homebrew

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/other-languages.md

Installs the standalone binary on macOS and Linux via Homebrew. No Node.js required.

```bash
brew install yusufaf/tap/sfn-diagram
```

--------------------------------

### Install sfn-diagram from JSR with Deno

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/installation.mdx

Installs the sfn-diagram package from JSR using Deno.

```bash
deno add jsr:@yusufaf/sfn-diagram
```

--------------------------------

### Build and install local .vsix

Source: https://github.com/yusufaf/sfn-diagram/blob/main/packages/vscode-sfn-diagram/README.md

Run these commands from the packages/vscode-sfn-diagram directory to produce a .vsix file and install it into VS Code. Requires pnpm and the VS Code CLI.

```bash
cd packages/vscode-sfn-diagram
pnpm install
pnpm package                       # produces vscode-sfn-diagram-<version>.vsix
code --install-extension vscode-sfn-diagram-*.vsix
```

--------------------------------

### Install sfn-diagram and @resvg/resvg-js with yarn

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/installation.mdx

Installs sfn-diagram along with the optional peer dependency @resvg/resvg-js for PNG export.

```bash
yarn add sfn-diagram @resvg/resvg-js
```

--------------------------------

### Install extension via Codium CLI (Open VSX)

Source: https://github.com/yusufaf/sfn-diagram/blob/main/packages/vscode-sfn-diagram/README.md

Install the extension from the Open VSX registry using the Codium CLI, which is the default for Cursor, Windsurf, VSCodium, Gitpod, and Eclipse Theia.

```bash
codium --install-extension yusufaf.vscode-sfn-diagram
```

--------------------------------

### Install sfn-diagram-react and sfn-diagram

Source: https://github.com/yusufaf/sfn-diagram/blob/main/packages/sfn-diagram-react/README.md

Install the package and its peer dependency. Use either npm or pnpm. Requires sfn-diagram >= 1.7.0.

```bash
npm install sfn-diagram-react sfn-diagram
# or
pnpm add sfn-diagram-react sfn-diagram
```

--------------------------------

### Install optional peer and render live state machine with --from-aws

Source: https://github.com/yusufaf/sfn-diagram/blob/main/README.md

Install the optional peer dependency @aws-sdk/client-sfn needed for --from-aws, then render a live state machine from its ARN to an SVG file. The region is derived from the ARN and credentials come from the AWS SDK's default chain, so AWS_PROFILE, SSO, and instance roles work as with the AWS CLI. The flag accepts a state machine, version, or alias ARN (not a bare name), is repeatable with --out-dir, and combines with --diff, --execution, and --check.

```bash
pnpm add @aws-sdk/client-sfn   # optional peer, only needed for --from-aws
sfn-diagram --from-aws arn:aws:states:us-east-1:111122223333:stateMachine:Orders -o live.svg
```

--------------------------------

### Follow execution with --follow

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Add --follow to keep updating the output file until the execution finishes. The example writes to an HTML file.

```bash
sfn-diagram order.asl.json \
  --execution arn:aws:states:us-east-1:111122223333:execution:Orders:run-1 \
  --follow -o run.html
```

--------------------------------

### Install sfn-diagram via npm

Source: https://github.com/yusufaf/sfn-diagram/blob/main/README.md

Installs the core package, which includes no browser engine or native rasterizer. SVG and Mermaid generation remain lightweight.

```bash
npm install sfn-diagram
```

--------------------------------

### Install Step Functions Diagram extension via CLI

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/ecosystem/vscode.md

Install the extension from the command line using the VS Code CLI. This is an alternative to searching for 'Step Functions Diagram' in the Extensions panel.

```bash
code --install-extension yusufaf.vscode-sfn-diagram
```

--------------------------------

### Config file error example

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Shows the error output and exit code when a config file contains an invalid theme.

```bash
$ sfn-diagram state.asl.json --config ci/sfn.json
Error: Invalid theme in /repo/ci/sfn.json: expected 'light', 'dark', or a custom theme object
$ echo $?
1
```

--------------------------------

### Install sfn-diagram with PNG support

Source: https://github.com/yusufaf/sfn-diagram/blob/main/README.md

Adds the optional peer dependency @resvg/resvg-js for PNG export. Only needed if you use sfn-diagram/png.

```bash
npm install sfn-diagram @resvg/resvg-js
```

--------------------------------

### Lint a Definition with lintAsl

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/examples.md

Runs lintAsl on an ASL definition to get diagnostics. lintAsl never throws; it returns an array of diagnostics with codes like 'unreachable-state' and severity levels. The example exits with code 1 if any error-severity diagnostic is found.

```typescript
import { lintAsl } from 'sfn-diagram';

const diagnostics = lintAsl({ definition: asl });
// [
//   { code: 'unreachable-state', severity: 'warning', path: '/States/Audit',
//     message: 'State "Audit" is unreachable from StartAt "Validate"' },
// ]

if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
  process.exit(1);
}
```

--------------------------------

### Download and run standalone binary directly

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/other-languages.md

Downloads the Linux x64 standalone binary, makes it executable, and verifies the version. Substitute your platform; Windows uses sfn-diagram-windows-x64.exe. The standalone build lacks AWS flags and PNG format.

```bash
curl -fsSL -o sfn-diagram \
  https://github.com/yusufaf/sfn-diagram/releases/download/sfn-diagram-v1.8.0/sfn-diagram-linux-x64  # x-release-please-version
chmod +x sfn-diagram
./sfn-diagram --version
```

--------------------------------

### Using the config file with CLI flags

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Shows how to use the config file by default, override it with a flag, and specify a custom config path.

```bash
sfn-diagram state.asl.json -o diagram.svg               # uses the file
sfn-diagram state.asl.json -o diagram.svg --layout TB   # the flag wins
sfn-diagram state.asl.json -o diagram.svg --config ci/sfn.yaml
```

--------------------------------

### Follow with --from-aws

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Use --from-aws to fetch the state machine definition and --execution with --follow to render a running execution. Note that --from-aws returns the current definition, which may not match the one used for the run.

```bash
sfn-diagram --from-aws arn:...:stateMachine:Orders \
            --execution arn:...:execution:Orders:run-1 --follow -o run.html
```

--------------------------------

### Fetch and render a state machine from AWS with --from-aws

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Fetches a state machine definition from AWS using DescribeStateMachine and renders it to a file. Requires the optional peer dependency @aws-sdk/client-sfn.

```bash
sfn-diagram --from-aws arn:aws:states:us-east-1:111122223333:stateMachine:Orders -o live.svg
```

```bash
pnpm add @aws-sdk/client-sfn
```

--------------------------------

### ASL definition example: order-processing workflow

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/introduction.md

An example ASL definition for an order-processing workflow, used to demonstrate sfn-diagram's rendering. It includes Pass, Choice, Task, Fail, and Succeed states.

```jsonc
{
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": { "Type": "Pass", "Next": "CheckStock" },
    "CheckStock": {
      "Type": "Choice",
      "Choices": [{ "Variable": "$.inStock", "BooleanEquals": true, "Next": "ChargePayment" }],
      "Default": "CancelOrder"
    },
    "ChargePayment": { "Type": "Task", "Resource": "arn:aws:lambda:...:charge-payment", "Next": "ShipOrder" },
    "ShipOrder":     { "Type": "Task", "Resource": "arn:aws:lambda:...:ship-order", "Next": "OrderComplete" },
    "CancelOrder":   { "Type": "Fail", "Error": "OutOfStock" },
    "OrderComplete": { "Type": "Succeed" }
  }
}
```

--------------------------------

### Use --from-aws with npx and the AWS SDK

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Shows how to run --from-aws via npx when the standalone binary is not available, explicitly including the @aws-sdk/client-sfn package.

```bash
npx --package sfn-diagram --package @aws-sdk/client-sfn sfn-diagram --from-aws arn:...
```

--------------------------------

### Example lint output

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Example output from the --check command. Each line shows severity, a JSON Pointer to the offending value, the message, and the rule code. The final line reports the total counts of errors and warnings.

```text
error   /States/Ship/Next  State "Ship" sets both "End: true" and "Next"  [end-with-next]
warning /States/Audit  State "Audit" is unreachable from StartAt "Validate"  [unreachable-state]
1 error, 1 warning
```

--------------------------------

### Run sfn-diagram via Docker for SVG and PNG output

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/cli.mdx

Runs the prebuilt Docker image from GitHub Container Registry, mounting the current directory to /work. The first command generates an SVG diagram, the second generates a PNG diagram. The image includes the PNG rasterizer, so `--format png` works without extra setup.

```bash
docker run --rm -v "$PWD":/work ghcr.io/yusufaf/sfn-diagram:latest \
  /work/state.asl.json --format svg -o /work/diagram.svg
```

```bash
docker run --rm -v "$PWD":/work ghcr.io/yusufaf/sfn-diagram:latest \
  /work/state.asl.json --format png -o /work/diagram.png
```

--------------------------------

### Redact hook example for generateHtml

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/configuration.md

Example of using the redact option in generateHtml to redact payloads and Parameters fields. The hook is called per state and per field; returning undefined redacts the value, inlining '[redacted]' (exported as REDACTED).

```typescript
const { html } = generateHtml({
  aslDefinition: asl,
  redact: ({ kind, path, value }) =>
    kind === 'payload' || path.endsWith('.Parameters') ? undefined : value,
});
```

--------------------------------

### CustomTheme partial override example

Source: https://github.com/yusufaf/sfn-diagram/blob/main/site/src/content/docs/guides/configuration.md

Shows how to create a custom theme by overriding only specific fields. The 'bigDark' theme sets base to 'dark' and fontSize to 18, while 'greenTasks' overrides only the Task fill color, leaving other colors from the base theme. The example also demonstrates passing the theme to generateSvg.

```typescript
import type { CustomTheme } from 'sfn-diagram';

// Dark theme, bigger labels
const bigDark: CustomTheme = { base: 'dark', fontSize: 18 };

// Light theme with a different Task fill — the Task stroke and every other colour stay
const greenTasks: CustomTheme = { nodeColors: { Task: { fill: '#e8f5e9' } } };

generateSvg({ aslDefinition: asl, theme: bigDark });
```
Tokens:
Raw