We’re excited to share a feature that unlocks a whole new level of power and flexibility in Stately’s editor: sources. With sources, you can now provide implementation source code for your actions, actors, and guards, making syncing between the editor and your codebase a breeze.

One of the most significant benefits of using our Stately editor is using your state machines as a source of truth. Using your state machines as live documentation relies upon bi-directionally syncing between visualizing your state machine and integrating the implementation code in your codebase. Previously, we had workarounds for bi-directional work; you could use the XState VS Code extension or add your implementation code after exporting your machine. You could even keep your machine in a separate file from your implementations to make it easier to replace your machine code with the exported code without overwriting your implementations. But you couldn’t provide implementation code in the editor, and importing your implementations from an existing machine would lose them. But that has all now changed with the introduction of sources!

Watch a demo of sources from our office hours at the end of December:

▶️ Jump straight to the video chapter on sources.

What are sources?

Using the Sources panel, you can now provide source code for your actions, actors, and guards implementations from inside Stately’s editor.

You can add custom source code from the Sources panel to suit your needs or choose from logic templates. Your source code will be included in your live actors, synced projects, and exported code, as found in the Code panel. When an action, actor, or guard is selected, the Sources panel shows its source code. When no item is selected on the canvas, the Sources panel shows all the sources for your current machine.

Logic templates

You can also choose from logic templates when editing the sources for your actions, actors, or guards. Use the template buttons to quickly add the implementation code for XState’s logic creators, higher-level guards, and built-in actions, and the correct XState imports will be added to your code for sync or export.

And yes, this means that we can now import your existing source code from your state machines, visualize them on the canvas, show them as sources in the studio, and keep your original code intact when exporting or syncing back to your codebase. In short, if you’re going back and forth between your codebase and Stately’s editor, you don’t have to worry about the implementation code getting lost or overwritten.

XState built-in actions

Previously, when you added an action to your machine in the editor, you’d have the option to make it a custom action or choose from one of XState’s built-in actions, including assign(), raise(), and sendTo(). Those built-in actions are now shown as fully editable logic templates in the sources panel, and built-in actions are still shown with their action type on the canvas.

Actions, actors, and guards are now named

Previously, not all actions, actors, and guards had names, especially if you had imported inline actions or inline guards from your XState machines. Now, when creating new actions, actors, or guards on the canvas, you’ll be prompted to give them a name, which is an important addition when importing source code from existing XState machines.

Importing sources from existing XState machines

When importing a machine from your codebase, we’ll give your unnamed actions, actors, and guards a default name based on their position in your machine config. For example, the following action:

createMachine({
  states: {
    a: {
      states: {
        b: { entry: [assign({ name: 'laura' })] },
      },
    },
  },
});

Would be given a default name of inline:(machine).a.b#entry[0]. These default names are not visible in the editor but will be used in the synced or exported code unless you give your action, actor, or guard a name. inline: is prepended to the name to make them more readable and easier to find in your code. After first importing your machine, we recommend you give all your actions, actors, and guards a name. Naming is a one-time step, and you can always rename them later. Giving your sources distinct names also means that multiple actors, actions, or guards can reference them, which can be really useful when combined with parameters.

Action parameters

You can now add parameters to your actions! When adding or editing an action on the canvas, you can use the button to Add parameter. From here, you can add key-value pairs as parameters for dynamic input that can be used in your source code. Parameters don’t just open the possibility for more reusable actions; in the future, Simulation mode and live actors will be able to use these parameters to execute actions based on different inputs when simulating your machine.

Actor inputs are also coming soon… enabling you to provide dynamic input to the actor when it executes. Actor inputs will be a game-changing combination with sources for deployed workflows in Stately Sky!

Bi-directional editing with sources and GitHub sync

If you haven’t checked it out yet, watch Kevin’s demo of GitHub Sync, which we’re also releasing this week. GitHub Sync and sources are a powerful combination. With GitHub Sync, you don’t even need to use the export button to sync your machine with your codebase. And sources ensure that your code stays intact when syncing bi-directionally between your codebase and the editor.

Sources make Stately Sky more powerful

Sources also bring huge benefits to Stately Sky, as your live actors can now execute the source code from your actions, actors, and guards in the cloud.

The future

We’re excited about sources because of all the features they enable in Stately Studio and your overall developer experience, helping Stately Studio become the visual collaborative source of truth for your app logic and workflows.

Using sources is free on all our plans, and you can try our premium features, including GitHub Sync and Stately Sky, for free on a Pro plan or with your team on a Team plan. You can read more about sources in our docs, and please share your feedback with us on our social platforms or in our regular office hours live streams. If you want help getting started with sources or getting your team set up with Stately and XState, the Stately team is available for workshops and consulting, and you can book a demo call with us to learn more about how Stately can work for your team.