LiveState

This the elixir library for building servers for LiveState applications.

what-is-livestate

What is LiveState?

The goal of LiveState is to make building highly interactive web applications easier to build. Currently in most such applications clients send requests and receive responses from and to a server API. This essentially results in two applications, with state being managed in both in an ad hoc way.

LiveState uses a different approach. Clients dispatch events, which are sent to the server to be handled, and receive updates from the server any time application state changes. This allows state to have a single source of truth, and greatly reduces client code complexity. It also works equally well for applications where updates to state can occur indepently from a user initiated client side event (think "real time" applications such as chat, etc).

how-is-livestate-different-from-liveview

How is LiveState different from LiveView?

LiveState shares similar goals to LiveView, but takes a different approach which allows for building different kinds of applications. LiveView allows the user to write all of the application code, both server logic and view presentation logic, in Elixir, and manages the web client side of the application entirely. LiveState event handlers are written in Elixir and quite similar to LiveView event handlers, but LiveState relies on client code to render state and dispatch events. This trade-off keeps client side code simple, but allows LiveState to be used to build applications that are not as good of a fit for LiveView.

installation

Installation

This package can be installed by adding live_state to your list of dependencies in mix.exs:

def deps do
  [
    {:live_state, "~> 0.7.0"},
    {:cors_plug, "~> 3.0"}
  ]
end

While cors_plug is not strictly required, you will very likely want it to be able to add to your endpoint so that clients cannot connect to your channel.

usage

Usage

First you need to setup a socket as you would with normal other Phoenix Channels

  1. On your Endpoint module, setup a socket for your channel:
    defmodule MyAppWeb.Endpoint do
      socket "/socket", PgLiveHeroWeb.Channels.LiveStateSocket
    ...
  2. Then create the socket module with the topic to listen to:
    defmodule MyAppWeb.Socket do
      use Phoenix.Socket
    
      channel "topic", MyAppWeb.Channel
      @impl true
      def connect(_params, socket), do: {:ok, socket}
    
      @impl true
      def id(_), do: "random_id"
    end
  3. Create you channel using the LiveState.Channel behaviour:
defmodule MyAppWeb.Channel do
  use LiveState.Channel, web_module: MyAppWeb
...
  1. Then want to define your initial state using the LiveState.Channel.init/3 callback which will be called after channel joins and is expected to return the initial state:
def init(_channel, _payload, _socket), do: {:ok, %{foo: "bar"}}

State must be a map. It will be sent down as JSON so anything in it must have a Jason.Encoder implementation.

events

Events

For events emitted from the client, you implement the LiveState.Channel.handle_event/3 callback. If you need access the socket in your event handler, you may implement LiveState.Channel.handle_event/4.

  def handle_event("add_todo", todo, %{todos: todos}) do
    {:noreply, %{todos: [todo | todos]}}
  end

LiveState.Channel.handle_event/3 receives the following arguments

  • event name
  • payload
  • current

And returns a tuple whose last element is the new state. It can also return one or many events to dispatch on the calling DOM Element:

  def handle_event("add_todo_with_one_reply", todo, %{todos: todos}) do
    {:reply, %Event{name: "reply_event", detail: %{foo: "bar"}}, %{todos: [todo | todos]}}
  end

  def handle_event("add_todo_with_two_replies", todo, %{todos: todos}) do
    {:reply,
     [
       %Event{name: "reply_event1", detail: %{foo: "bar"}},
       %Event{name: "reply_event2", detail: %{bing: "baz"}}
     ], %{todos: [todo | todos]}}
  end

documentation

Documentation

phx-live-state

phx-live-state

The front end library npm package that implements sending and receiving events, and subscribing to state changes. It also facilitates building Custom Elements that are backed by LiveState.

use-live-state

use-live-state

A react hook for LiveState.

live_state_testbed

live_state_testbed

This is a phoenix project that mainly provides integration tests for LiveState. It's also a great place to see examples of how to use LiveState

other-resources

Other resources

There are several examples of full LiveState projects. This blog post covers building a embeddable comments section custom element. The relevant source code repos:

This talk from ElixirConf 2022 also covers LiveState in detail. The code examples from the talk are in the repos below: