Debugging & Running Locally

A guide explaining how you can debug your code locally, without deploying it to STATEWIZE, and while utilising your existing code editor, logs, line-by-line debugging, etc.

Debugger setup

In order to debug code locally while still using the STATEWIZE dashboard - you need to install 2 dependencies.

  1. A global statewize-dev-server - which serves as a local development/debugging server on your machine. Here's a link.

  2. A local dev dependency called statewize-dev-client - add that to the project which you want to debug. Currently it's available for Javascript via NPM, and a Python release is coming soon.

Installing the Dev Server

Start by installing the STATEWIZE dev server:


$ npm install -g statewize-dev-server

The DEV server simulates the STATEWIZE execution environment on your local machine

Once it's installed, you can launch it like so:

$ npx statewize-dev-server

Installing the Dev Client

$ yarn add -D statewize-dev-client


$ npm install -D statewize-dev-client

Once it's installed, edit your main file to start the STATEWIZE dev environment (Please ensure you only do so in your local environment, and please ensure it's not going to run in production!)

Javascript / Typescript
Javascript / Typescript
import {dev} from "statewize-dev-client";

The dev function, imported from the statewize-dev-client library, will allow you to both debug your local code, and to provide mocks as states' outputs.

Debugging & Mocking

Let's assume we have a flow that looks like this:

test flow

Now, we want to achieve 2 things:

  1. Mock the output of "mocked-state" to always return a mock JSON

  2. Debug the code of "sunshine-state" - line by line, in our own IDE.

To do so, we need to "map" the state name to its implementation, or its mock, inside the STATEWIZE dev wrapper:

import {dev} from "statewize-dev-client";
import sunshine from "./sunshine";
'mocked-state': {
path: "pathToMock.json",
handler: {a: 123, mock: true}
'sunshine-state': {
path: require.resolve('./sunshine'),
handler: sunshine

As you can see, we've mapped our mocked-state to a mock object, which will always return { "a": 123, "mock": true } . In addition, we are forcing the state sunshine-state to run our code from the local filesystem. (function sunshine from the file ./sunshine.ts.)

You must provide both the handler (whether it's a function to invoke, or a mock object to return), as well as the path to that handler using require.resolve(importPath)

Now, debug your project (like you usually would, for example via node index.js). Once you have started your project (which contains the dev command from statewize-dev-client) you can toggle the local debugger on the STATEWIZE web platform:

Now you can freely execute your code, as usual, and see debug it in real time:

Debugging side by side

Dev mode for statewize-client-sdk

It is possible to use statewize-client-sdk in order easily integrate your existing frontend or backend applications with STATEWIZE, so that they invoke executions as and when necessary. (more information is available here)

You can configure the statewize-client-sdk to work with your local statewize-dev-server by simply passing a boolean true into the client constructor:

const {StateWizeClient} = require('statewize-client-sdk');
const sdk = new StateWizeClient(process.env.DEV_MODE);

It defaults to false, so if you don't pass anything - the dev server will NOT be used. So it's safe to pass nothing in production.

Please make sure to only pass true in local environments.

Synchronizing your local code with STATEWIZE origin

When debugging locally, your local code stays on your machine - it's not being uploaded to STATEWIZE at any point.

Once you've finished debugging, you may want to deploy your code to STATEWIZE origin, so that it's accessible outside of your local machine. To do so, in debugging mode, you can click on the "Sync" button near the debugging toggle under the main flow canvas. This will trigger a deployment of all the connected source code functions to STATEWIZE.

This is like pushing your code to origin.

Mocks will not be deployed - only actual functions which are mapped to states - will be deployed.

The updated flow will not be saved in any environment, rather it's just going to be saved as a development snapshot, which you can continue editing once the local debugger is disconnected.

Deployment logs are available in the same shell where you executed statewize-dev-server.