In this tutorial, we are going to build a small chat app using Actyx. You might be tempted to skip it because you are not building chats in real-life — give it a chance. The techniques that you will learn in this tutorial are fundamental to building anything on the platform, and mastering them will give you a good understanding of its capabilities.
The tutorial is divided into three sections:
- We will get set up for the tutorial
- We will quickly introduce Actyx
- We will get to it and build the chat
You don’t have to complete all of the sections at once to get value out of this tutorial. Try to get as far as you can — even if it’s just one or two sections.
To get the most out of this tutorial, it is helpful if you have basic knowledge of HTML, CSS, and TypeScript. But since this is a fairly simple example you should be able to follow along even if you are coming from a different programming language.
Typescript in 5 minutes
If you haven't worked in TypeScript before, we can recommend this guide to learn the basics.
Now, let's get right to it. In this section, we will install Actyx and set up a basic project for our chat.
- Download Actyx for Windows
- Double click and run through the installer
- Start Actyx via the Start Menu; a tray icon will appear
In order to run, test and build the chat app you are going to need Node.js and npm, which you can install from here.
We are now going to set up a simple web app project using Parcel. Somewhere on your computer create a directory called
In that directory create a file called
package.json and add the following content:
Create another file called
tsconfig.json with the following content:
Now create a file called
index.html and add the following:
Finally, create a file named
index.ts with the following content:
To test that everything works, open a terminal, navigate to the
chat directory and run
npm install and then
npm run start. This is what you should see in your terminal.
If you now navigate to http://localhost:1234 in your browser and open the Developer Tools you should see this:
Actyx is a platform for building highly resilient software systems distributed across a swarm of networked devices. Specifically you can:
- Implement business logic as low-code twins
- Include your twins in apps running on devices
- Forget about the network and data persistence
Actyx enables a completely decentralized architecture that allows you to build apps that always runs. Your apps always run because they run locally on the device and only interact with the locally running Actyx software.
Enough theory! Let's jump right in.
Let's now have a look at how Actyx makes it super simple to build a decentralized chat.
To build and run our chat we need to do three things:
Install Actyx on each deviceAlready done!
- Implement our chat logic as a twin
- Integrate the twin into an app
Our chat logic is simple. Anyone can send messages and receives messages sent by all others. When someone joins the chat, they receive all past messages that were sent before they joined.
The way to implement this using Actyx is to write a so-called twin. A twin is a state-machine. It has a state which it updates when it receives information from elsewhere.
Let's start by defining types for the chat twin's state and the events it can receive. In this case, we have one type of event which is simply a message (string). The state of the twin is an array of strings. In the
index.ts file, add the following two lines of code:
When a twin first starts up, it won't have any messages in memory. So let's give it an empty array as the initial state:
Now to the chat twin's logic, i.e. how to calculate the chat state, which we will show to the user, from the events we have received. We implement it as a so-called
onEvent function. This function simply adds any message it received as a
ChatEvent to our
This is the complete chat logic. Let's now turn this into a fish.
Twin == Fish
The Actyx library that allows you to write twins, actually calls them Fishes. You will see below, but Twin == Fish!
A fish, aka twin, is defined as an object with a couple of properties. You must provide the fish with an ID, an initial state, the
onEvent function and information about where to get the chat messages from, a so-called event stream tags.
First, add the following imports to the top of the
Now that we have done that, we create the tag for our chat messages and then define the fish itself:
That's it. You can now import this fish into any application and it will automatically be synchronized across your network.
Lastly, we need to build a user interface and hook up our fish. Let's implement a very simple user interface showing the chat messages, an input field to type a message and a button to send the message.
Open up the
index.html file and adjust the contents of the
body sections as follows:
The last thing we have to do is to hook up the user interface to the fish. We want to
- Show all chat messages, i.e. fish's state in the
- Send out a chat message event when the user clicks the Send button
index.ts file, add the following code:
To test that everything works navigate to the
chat directory, run
npm run start and open http://localhost:1234. You should now see the chat app.
At this point you are chatting by yourself. What's the point?
What Actyx allows you to do now is run this chat app on as many computers as you want in your network. Actyx will automatically synchronize the chat twin across all those devices.
The power of this is that you do not have to worry about programming the network, nor about setting up some central database for storage. You only think: local-first.
And, your user can use the app whenever his device is on. Even when he is in airplane mode. Actyx will sync the twin when he gets back into the network. This is local-first.
And just like that you have built a decentralized app that would traditionally have required a web server and a shared database or pub-sub broker 🎉
Here is what you can try out now:
- Run the chat app on another computer in the network
- Restart the app: do you see the chat history?
- Airplane mode: what happens if you chat while offline?
- Reconnecting: what happens when you disable airplane mode again?
We hope that you are now starting to experience the power of local-first cooperation and the Actyx Platform. If you are keen to dive a bit deeper, check out the following further resources.
You can download the complete code for this tutorial from GitHub here.
- Move onto the advanced tutorial to implement a factory use-case
- Visit our how-to guides to get started immediately
- Dive into how it works with the Conceptual Guides
Join our Discord chat
Feel free to join our Actyx Developer Chat on Discord. We would love to hear about what you want to build on the Actyx Platform.