You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Tweak readme copy
* Fix layout of navbar between 997 and 1049px
* Specify tools used for Sky example
* Tweak language to make more concise
* Format for referring to at-a-glance
* Replace image with embedded machine
This guide will walk you through the process of creating a simple traffic light actor using Stately Sky.
8
-
**Please note that Sky is currently in alpha and will be changing rapidly**.
7
+
This guide will walk you through deploying a simple traffic light state machine actor with Stately Sky using [XState](/docs/xstate.mdx), [Vite](https://vitejs.dev/) and [React](https://reactjs.org/).
9
8
10
-
## Prerequisites
9
+
:::caution
11
10
12
-
1. A Stately account with a [Pro or Enterprise subscription](https://stately.ai/pricing)
13
-
2. Our Stately Sky starter project. [Clone the repo to your local machine](https://github.com/statelyai/sky-starter-app)
14
-
3. A machine to deploy as an actor. To test, feel free to fork our [stop light example](https://stately.ai/registry/editor/eb3e89f5-5936-439f-8254-2f6ea4303659?machineId=15fd8071-b80c-4a6f-b9f5-60b6cf578ee5)
11
+
Please note that Sky is currently in alpha and will be changing rapidly.
12
+
13
+
:::
14
+
15
+
## What you’ll need
16
+
17
+
- A [Stately](https://stately.ai) account with a [Pro or Enterprise subscription](https://stately.ai/pricing).
18
+
- Our [Stately Sky starter project](https://github.com/statelyai/sky-starter-app). Clone the repo to your local machine.
15
19
16
20
## Getting started video
17
21
18
22
<YouTubeid="A_J1jbz1oWw" />
19
23
20
-
## Step 1: Create a machine in the Studio
24
+
## Step 1: Create a machine with Stately
25
+
26
+
Create a project and compose your machine in the [Stately editor](https://stately.ai/editor) with the transitions and states you want.
21
27
22
-
Create a project and compose your machine in the Studio 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`.
28
+
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](https://stately.ai/registry/editor/eb3e89f5-5936-439f-8254-2f6ea4303659?machineId=15fd8071-b80c-4a6f-b9f5-60b6cf578ee5) to test.
23
29
24
-
Sky only supports XState V5 machines. The changes in V5 provide both a better developer experience and adhere to the Actor Model more closely, allowing for Sky to capably deploy machines that reliably communicate their state.
36
+
Sky only supports [XState](https://github.com/statelyai/xstate) V5 machines. The [changes in XState V5](/docs/migration.mdx) provide both a better developer experience and adhere to the [Actor Model](/docs/actor-model.mdx) more closely, allowing Sky to capably deploy machines that reliably communicate their state.
28
37
:::
29
38
30
39
## Step 2: Create an API key
31
40
32
-
When you've finished creating your machine, you'll need to create an API key to deploy it to Sky. You can do this by clicking the "Run" button in the top right corner of the Studio. A screen will appear, prompting you to create an API key. Select that button.
41
+
After creating your machine, you’ll need to create an API key to deploy it to Sky.
42
+
43
+
1. Use the **Run** button in the top right corner of the editor to open the Stately Sky options.
44
+
2. Use the **Create API Key** button to generate an API key.
33
45
34
46
35
47
36
-
Be sure to copy that API key and save it somewhere safe. You'll need it later. The page should look like this:
48
+
3. Be sure to copy that API key and save it somewhere safe. You’ll need it later.
Now that the API key is generated, you can deploy your machine to Sky as a running actor. Select the "Deploy new actor" button to start the process. Once the actor is deployed, the page will display the name of the running actor and the URL you can use to interact with it. You'll need to use that URL to communicate with the actor from the starter project.
56
+
Once you have generated the API key, you can deploy your machine to Sky as a running actor.
57
+
58
+
1. Use the **Deploy new actor** button to start the deployment process.
59
+
2. When the actor is deployed, it will be listed under **Existing deploys**.
60
+
3. Use **Copy URL** to copy to the URL to your clipboard.
61
+
62
+
You’ll need the running actor’s URL to communicate with that actor from the starter project.
## Step 4: Add your API key to the starter project
47
67
48
-
Start by opening [the starter project](https://github.com/statelyai/sky-starter-app) in your code editor. Next install the packages using your package manager of choice:
68
+
1. Open [the starter project](https://github.com/statelyai/sky-starter-app) in your code editor.
69
+
2. Install the packages using your package manager of choice:
49
70
50
71
```bash npm2yarn
51
72
npm install
52
73
```
53
74
54
-
At the root of the project, create a `.env` file to hold your API key.
55
-
There are 2 variables that need to be set in the `.env` file, paste your API key as the value for both these keys:
75
+
3.At the project’s root, create a `.env` file to hold your API key.
76
+
4. Set the following two variables in the `.env` file; paste your API key as the value for both these keys:
56
77
57
-
1.`SKY_API_KEY` (used by the `@xstate/cli` to fetch the machine config).
58
-
2.`VITE_SKY_API_KEY` (used by the Vite React app to connect to Sky).
78
+
-`SKY_API_KEY`: used by the `@xstate/cli` to fetch the machine config.
79
+
-`VITE_SKY_API_KEY`: used by the Vite React app to connect to Sky.
## Step 5: Initialize the actor in the starter project
63
84
64
-
After adding the API key, you'll need to initialize the actor. Create a new file in the `src` directory of the starter project. We named ours `trafficLightActor.ts`. In that file, import the `actorFromStately` function and initialize the actor with the provided URL and your own session ID. The session ID can be any string you want. We recommend using a UUID:
85
+
After adding the API key, you’ll need to initialize the actor.
86
+
87
+
1. Create a new file in the `src` directory of the starter project. We named ours `trafficLightActor.ts`.
88
+
2. In your new file, import the `actorFromStately` function and initialize the actor with the provided URL and your own session ID:
65
89
66
90
```typescript
67
91
import { actorFromStately } from'@statelyai/sky';
@@ -72,34 +96,46 @@ const actor = actorFromStately({
72
96
});
73
97
```
74
98
99
+
The session ID can be any string you want. We recommend using a UUID.
100
+
75
101
:::tip
76
-
By default Sky is multiplayer. We make use of the session ID to allow multiple tenants to reference the same running actor instance.
102
+
By default Sky is multiplayer. We use the session ID to allow multiple tenants to reference the same running actor instance.
77
103
:::
78
104
79
105
## Step 6: Fetching the actor config from Sky
80
106
81
-
Now that we've initialized 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 typesafety when interacting with the running actor!
107
+
Now that we’ve initialized 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!
82
108
83
-
To fetch the config, we'll use the XState CLI tool. In our `package.json`, we already have a reference to the script we need to run, named `sky`. This runs the command over all the files in the `src` repo to find configs associated with any initialized actors.
109
+
To fetch the config, we’ll use the [XState CLI tool](/docs/developer-tools.mdx#xstate-cli-command-line-interface) 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.
Using your package manager of choice, run the `sky` command. For convenience, feel free to use one of the npm or yarn commands below:
113
+
1.Using your package manager of choice, run the `sky` command:
88
114
89
115
```bash npm2yarn
90
116
npm run sky
91
117
```
92
118
93
-
Once completed, you should see a second argument passed to the `actorFromStately` function, with the name `skyConfig` and updated imports. You should also see a new TypeScript file in your `src` directory, named after the actor in the Studio. In our case, it's `trafficLightActor.sky.ts`.
119
+
2. Once the `sky` command has completed, you should see:
120
+
121
+
- a second `skyConfig` argument with updated imports passed to the `actorFromStately` function.
122
+
- a new TypeScript file in your `src` directory, named after the actor in the Studio. In our case, it’s `trafficLightActor.sky.ts`.
123
+
124
+
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.
125
+
126
+
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`.
127
+
128
+
:::tip
129
+
130
+
Add your generated `sky.ts` files to source control.
And that's it! You're now able to interact with your running actor in much the same way you would with local ones, like sending events with the `send()` function. This is still in early days, so there are some limitations and things to remember. Specifically:
138
+
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:
100
139
101
140
- Only XState V5 machines are supported.
102
141
- Delayed transitions are not yet supported, but will be soon.
103
-
- The generated `sky.ts` files are meant to be added to source control.
104
-
- You'll notice a warning in the `sky.ts` file that the file is generated. You should not manually edit these files. Any local changes will not reflect what's running in Sky.
105
-
- 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`.
0 commit comments