Skip to content
Version: XState v5

Getting started with Stately Sky 🌤️

This guide will walk you through deploying a simple traffic light state machine workflow with Stately Sky using XState, Vite and React.

What you’ll need​

Getting started video​

Step 1: Create a machine with Stately​

Create a project and compose your machine in the Stately editor with the transitions and states you want.

For this example, we’ll create a simple traffic light machine with three states: green, yellow, and red. Feel free to fork our traffic light example to test. Check out a deployed version of this traffic light machine.

Step 2: Create an API key​

After creating your machine, you’ll need to create an API key to deploy it to Sky.

  1. Use the Deploy button in the top right corner of the editor to open the Stately Sky options.
  2. Use the Create API Key button to generate an API key.

Stately Sky modal showing no API key created yet. There is a button to Create API Key.

  1. Be sure to copy that API key and save it somewhere safe. You’ll need it later.

The page should look like this:

Stately Sky modal shows the API key in an input hidden behind password dots. There are options to Regenerate, Delete, Reveal, or copy the API key to the clipboard.

Step 3: Deploy your machine to Sky​

Once you have generated the API key, you can deploy your machine to Sky as a workflow.

  1. Use the Deploy to Sky 🌤️ button to start the deployment process.
  2. When the workflow is deployed, it will be listed under Existing deploys.
  3. Use Copy URL to copy to the URL to your clipboard.

You’ll need the workflow’s URL to reference it from the starter project.

Stately Sky modal shows the Traffic light workflow listed under Existing deploys. The workflow has its own URL with the options to Copy URL or delete alongside.

Step 4: Add the actor in the starter project​

After adding the API key, you’ll need to create an actor.

  1. Create a new file in the src directory of the starter project. We named ours trafficLightActor.ts.
  2. In your new file, import the actorFromStately function and initialize the actor with the provided URL and your own session ID:
import { actorFromStately } from '@statelyai/sky';

const actor = actorFromStately({
  apiKey: 'paste your API key here',
  url: 'paste your Sky url here',
  sessionId: 'your session id here',
});

Step 5: Fetching the config from Sky​

Now that we’ve created the actor, we need to fetch the config from Sky. Doing so will download and generate the machine configuration file in our repo, giving us type safety when interacting with the running actor!

To fetch the config, we’ll use the XState CLI tool and the sky script already in our package.json. This script runs the command over all the files in the src repo to find configs associated with any initialized actors.

package.json

  1. Using your package manager of choice, run the sky command:
npm run sky
  1. Once the sky command has completed, you should see:
  • a second skyConfig argument with updated imports passed to the actorFromStately function.
  • a new TypeScript file in your src directory, named after the actor in the Studio. In our case, it’s trafficLightActor.sky.ts.

You’ll notice a warning in the sky.ts file that the file is generated. You should not manually edit these files as any local changes will not reflect what’s running in Sky.

Running xstate sky will only affect a file if it hasn’t already been fetched. If you make changes to the machine in the Studio, you’ll need to delete the generated file yourFile.sky.ts and run the command again. Alternatively, you can force the refetch by running xstate sky --refetch.

Finishing up​

And that’s it! You can now interact with your running actor in much the same way you would with local actors, like sending events with the send() function. Sky is still in its early days, so there are some limitations and things to remember. Specifically:

  • Only XState V5 machines are supported.
  • If you're using React Native, see this comment if you're having issues.