Welcome to LiveStash

Copy Markdown View Source

LiveStash provides a reliable, explicit API to safely stash and recover Phoenix LiveView assigns, keeping your application state completely intact whenever a socket connection is interrupted or re-established.

Usage

Adding LiveStash to your existing LiveView is very simple.

  1. Add use LiveStash to your module. It registers LiveStash's on_mount hook, which initializes stash support for the socket. See LiveStash.__using__/1.
defmodule ShowcaseAppWeb.CounterLive do
  use LiveStash
  1. Decide which part of your LiveView state you want to stash.
  def handle_event("increment", _, socket) do
    socket
    |> assign(:count, socket.assigns.count + 1)
    |> assign(:user_id, 123)
    |> LiveStash.stash_assigns([:count, :user_id]) # pass the list of assigns that you want to stash
    |> then(&{:noreply, &1})
  end
  1. Call recover_state(socket) in your mount/3 function call. It will automatically restored assigns to your socket.
  def mount(_params, _session, socket) do
    socket
    |> LiveStash.recover_state()
    |> case do
        {:recovered, recovered_socket} ->
          # socket with previously stashed assigns is recovered
          recovered_socket

        {_, socket} ->
          # could not recover assigns, proceed with standard setup using returned socket
          # ...
    end
    |> then(&{:ok, &1})
  end

Installation

Add live_stash to your dependencies in mix.exs:

def deps do
  [
    {:live_stash, "~> 0.1.0"}
  ]
end

In your app.js, pass initLiveStash into the LiveSocket params:

import initLiveStash from "../../deps/live_stash/assets/js/live-stash.js";

const liveSocket = new LiveSocket("/live", Socket, {
  params: initLiveStash({ _csrf_token: csrfToken }),
  // ...
});

Storage modes

You can control where the stashed data is kept by passing appropriate adapter module. LiveStash currently supports two adapters:

  • ETS - (default) The data is kept on the server side in the ETS table.
  • Browser memory - The data is saved in the client browser.
use LiveStash, adapters: LiveStash.Adapters.ETS

Remember to define adapters you would like to activate in your config.exs file.

config :live_stash, adapters: [LiveStash.Adapters.ETS, LiveStash.Adapters.BrowserMemory]

The default adapter is LiveStash.Adapters.ETS and it is always activated.

See ETS Adapter Guide and Browser Memory Adapter Guide for details on how to customize LiveStash to your needs.

When not to use

LiveStash is meant for explicitly stashing server-side LiveView assigns that you truly need to survive reconnects. For a lot of state, there are better (and simpler) tools:

  • Pure UI toggles and ephemeral client state: For things like opening a modal, toggling a dropdown, or highlighting a row, prefer keeping the state on the client with Phoenix.LiveView.JS. For more complex interactions, use phx-hook to manage state locally in the browser.
  • Form inputs: LiveView includes built-in form auto-recovery that replays the form data after reconnect. If your main concern is users losing typed input, you likely don’t need LiveStash. See How Phoenix LiveView Form Auto-Recovery works.
  • Navigation/context state: For pagination, filters, sorting, and search terms, put the state in URL query params. This is the most resilient approach across reloads, reconnects, and shareable links.

Authors

LiveStash is created by Software Mansion.

Since 2012 Software Mansion is a software agency with experience in building web and mobile apps as well as complex multimedia solutions. We are Core React Native Contributors, Elixir ecosystem experts, and live streaming and broadcasting technologies specialists. We can help you build your next dream product – Hire us.

Copyright 2026, Software Mansion

Software Mansion