|
| 1 | +--- |
| 2 | +title: 'Stately Sky getting started' |
| 3 | +--- |
| 4 | + |
| 5 | +# Getting started with Stately Sky |
| 6 | + |
| 7 | +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**. |
| 9 | + |
| 10 | +## Prerequisites |
| 11 | + |
| 12 | +1. A Stately account with a [Pro or Enterprise subscription](https://stately.ai/pricing) |
| 13 | +2. The starter project. [Clone the repo on your local machine](https://github.com/statelyai/sky-starter-app/tree/main) |
| 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) |
| 15 | +4. A package manager, like [NPM](https://www.npmjs.com/package/npm) or [Yarn](https://yarnpkg.com/) |
| 16 | + |
| 17 | +## Step 1: Create a machine in the Studio |
| 18 | + |
| 19 | +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`. |
| 20 | + |
| 21 | + |
| 22 | + |
| 23 | +:::xstate |
| 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. |
| 25 | +::: |
| 26 | + |
| 27 | +## Step 2: Create an API key |
| 28 | + |
| 29 | +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. |
| 30 | + |
| 31 | + |
| 32 | + |
| 33 | +Be sure to copy that API key and save it somewhere safe. You'll need it later. The page should look like this: |
| 34 | + |
| 35 | + |
| 36 | + |
| 37 | +## Step 3: Deploy your machine to Sky |
| 38 | + |
| 39 | +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. |
| 40 | + |
| 41 | + |
| 42 | + |
| 43 | +## Step 4: Add your API key to the starter project |
| 44 | + |
| 45 | +Open the starter project in your code editor. At the root of the project, create a `.env` file to hold your API key. |
| 46 | +There are 2 variables that need to be set in the `.env` file: `SKY_API_KEY` and `VITE_SKY_API_KEY`. Paste your API key as the value for both these keys. |
| 47 | + |
| 48 | + |
| 49 | + |
| 50 | +:::tip |
| 51 | +The starter project relies on Vite to run the app. Vite uses the `VITE_` prefix for environment variables, so any code processed by Vite will not have access to any environment variables without that prefix. |
| 52 | +For code that Vite doesn't touch, however, we rely on the `SKY_API_KEY` variable. This is why we set both variables to the same value. |
| 53 | +::: |
| 54 | + |
| 55 | +## Step 5: Initialize the actor in the starter project |
| 56 | + |
| 57 | +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: |
| 58 | + |
| 59 | +```typescript |
| 60 | +import { actorFromStately } from '@statelyai/sky'; |
| 61 | + |
| 62 | +const actor = actorFromStately({ |
| 63 | + url: 'paste your actor url here', |
| 64 | + sessionId: 'your session id here', |
| 65 | +}); |
| 66 | +``` |
| 67 | + |
| 68 | +:::tip |
| 69 | +By default Sky is multiplayer. We make use of the session ID to allow multiple tenants to reference the same running actor instance. |
| 70 | +::: |
| 71 | + |
| 72 | +## Step 6: Fetching the actor config from Sky |
| 73 | + |
| 74 | +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! |
| 75 | + |
| 76 | +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. |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | +Using your package manager of choice, run the `sky` command. For convenience, feel free to use one of the npm or yarn commands below: |
| 81 | + |
| 82 | +```bash npm2yarn |
| 83 | +npm run sky |
| 84 | +``` |
| 85 | + |
| 86 | +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`. |
| 87 | + |
| 88 | + |
| 89 | + |
| 90 | +## Finishing up |
| 91 | + |
| 92 | +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: |
| 93 | + |
| 94 | +- Only XState V5 machines are supported. |
| 95 | +- Delayed transitions are not yet supported, but will be soon. |
| 96 | +- The generated `sky.ts` files are meant to be added to source control. |
0 commit comments