Legend-State is a super fast all-in-one state and sync library that lets you write less code to make faster apps. Legend-State has four primary goals:
- As easy as possible to use.
- The fastest React state library.
- Fine-grained reactivity for minimal renders.
- Powerful sync and persistence (with Supabase support built in!)
And, to put the cherry on top, it works with Expo and React Native (via React Native Async Storage). This makes it a perfect match for building local-first mobile and web apps.
In local-first software, "the availability of another computer should never prevent you from working" (via Martin Kleppmann). When you are offline, you can still read and write directly from/to a database on your device. You can trust the software to work offline, and you know that when you are connected to the internet, your data will be seamlessly synced and available on any of your devices running the app. When you're online, this architecture is well suited for "multiplayer" apps, as popularized by Figma.
To dig deeper into what local-first is and how it works, refer to the Expo docs.
A primary goal of Legend-State is to make automatic persisting and syncing both easy and very robust, as it's meant to be used to power all storage and sync of complex apps.
Any changes made while offline are persisted between sessions to be retried whenever connected. To do this, the sync system subscribes to changes on an observable, then on change goes through a multi-step flow to ensure that changes are persisted and synced.
- Save the pending changes to local persistence.
- Save the changes to local persistence.
- Save the changes to remote persistence.
- On remote save, set any needed changes (like updated_at) back into the observable and local persistence.
- Clear the pending changes in local persistence.
To set up a new React Native project you can use the create-expo-app utility. You can create a blank app or choose from different examples.
For this tutorial, go ahead and create a new blank Expo app:
_10
npx create-expo-app@latest --template blank
The main dependencies you need are Legend State and supabase-js. Additionally, to make things work for React Native, you will need React Native Async Storage and react-native-get-random-values (to generate uuids).
Install the required dependencies via expo install:
_10
npx expo install @legendapp/state@beta @supabase/supabase-js react-native-get-random-values @react-native-async-storage/async-storage
If you don't have a Supabase project already, head over to database.new and create a new project.
Next, create a .env.local file in the root of your project and add the following env vars. You can find these in your Supabase dashboard.
_10
EXPO_PUBLIC_SUPABASE_URL=
_10
EXPO_PUBLIC_SUPABASE_ANON_KEY=
Next, set up a utils file to hold all the logic for interacting with Supabase, we'll call it utils/SupaLegend.ts.
_10
import { createClient } from '@supabase/supabase-js'
_10
_10
const supabase = createClient(
_10
process.env.EXPO_PUBLIC_SUPABASE_URL,
_10
process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY
_10
)
Legend-State is very versatile and allows you to choose different persistence and storage strategies. For this example, we'll use React Native Async Storage for local persistence across platforms and supabase for remote persistence.
Extend your utils/SupaLegend.ts file with the following configuration:
_46
import { createClient } from '@supabase/supabase-js'
_46
import { observable } from '@legendapp/state'
_46
import { syncedSupabase } from '@legendapp/state/sync-plugins/supabase'
_46
import { configureSynced } from '@legendapp/state/sync'
_46
import { observablePersistAsyncStorage } from '@legendapp/state/persist-plugins/async-storage'
_46
import AsyncStorage from '@react-native-async-storage/async-storage'
_46
_46
const supabase = createClient(
_46
process.env.EXPO_PUBLIC_SUPABASE_URL,
_46
process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY
_46
)
_46
_46
// Create a configured sync function
_46
const customSynced = configureSynced(syncedSupabase, {
_46
// Use React Native Async Storage
_46
persist: {
_46
plugin: observablePersistAsyncStorage({
_46
AsyncStorage,
_46
}),
_46
},
_46
generateId,
_46
supabase,
_46
changesSince: 'last-sync',
_46
fieldCreatedAt: 'created_at',
_46
fieldUpdatedAt: 'updated_at',
_46
// Optionally enable soft deletes
_46
fieldDeleted: 'deleted',
_46
})
_46
_46
export const todos$ = observable(
_46
customSynced({
_46
supabase,
_46
collection: 'todos',
_46
select: (from) => from.select('id,counter,text,done,created_at,updated_at,deleted'),
_46
actions: ['read', 'create', 'update', 'delete'],
_46
realtime: true,
_46
// Persist data and pending changes locally
_46
persist: {
_46
name: 'todos',
_46
retrySync: true, // Persist pending changes and retry
_46
},
_46
retry: {
_46
infinite: true, // Retry changes with exponential backoff
_46
},
_46
})
_46
)
If you haven't alread, install the Supabase CLI and run supabase init to initialize your project.
Next, create the initial database migration to set up the todos table:
_10
supabase migrations new init
This will create a new SQL migration file in the supabase/migrations directory. Open it and add the following SQL code:
_34
create table todos (
_34
id uuid default gen_random_uuid() primary key,
_34
counter bigint generated by default as identity,
_34
text text,
_34
done boolean default false,
_34
created_at timestamptz default now(),
_34
updated_at timestamptz default now(),
_34
deleted boolean default false -- needed for soft deletes
_34
);
_34
_34
-- Enable realtime
_34
alter
_34
publication supabase_realtime add table todos;
_34
_34
-- Legend-State helper to facilitate "Sync only diffs" (changesSince: 'last-sync') mode
_34
CREATE OR REPLACE FUNCTION handle_times()
_34
RETURNS trigger AS
_34
$$
_34
BEGIN
_34
IF (TG_OP = 'INSERT') THEN
_34
NEW.created_at := now();
_34
NEW.updated_at := now();
_34
ELSEIF (TG_OP = 'UPDATE') THEN
_34
NEW.created_at = OLD.created_at;
_34
NEW.updated_at = now();
_34
END IF;
_34
RETURN NEW;
_34
END;
_34
$$ language plpgsql;
_34
_34
CREATE TRIGGER handle_times
_34
BEFORE INSERT OR UPDATE ON todos
_34
FOR EACH ROW
_34
EXECUTE PROCEDURE handle_times();
The created_at, updated_at, and deleted columns are used by Legend-State to track changes and sync efficiently. The handle_times function is used to automatically set the created_at and updated_at columns when a new row is inserted or an existing row is updated. This allows to efficiently sync only the changes since the last sync.
Next, run supabase link to link your local project to your Supabase project and run supabase db push to apply the init migration to your Supabase database.
Legend-State integrates with supabase-js to provide end-to-end type safety. This means you can use the existing Supabase CLI workflow to generate TypeScript types for your Supabase tables.
_10
supabase start
_10
supabase gen types --lang=typescript --local > utils/database.types.ts
Next, in your utils/SupaLegend.ts file, import the generated types inject them into the Supabase client.
_10
import { createClient } from '@supabase/supabase-js'
_10
import { Database } from './database.types'
_10
// [...]
_10
_10
const supabase = createClient<Database>(
_10
process.env.EXPO_PUBLIC_SUPABASE_URL,
_10
process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY
_10
)
_10
_10
// [...]
From here, Legend-State will automatically infer the types for your Supabase tables and make them available within the observable.
Above, you've configured the todos$ observable. You can now import this in your tsx files to fetch and automatically sync changes.
_12
import { observer } from '@legendapp/state/react'
_12
import { todos$ as _todos$ } from './utils/SupaLegend'
_12
_12
const Todos = observer(({ todos$ }: { todos$: typeof _todos$ }) => {
_12
// Get the todos from the state and subscribe to updates
_12
const todos = todos$.get()
_12
const renderItem = ({ item: todo }: { item: Tables<'todos'> }) => <Todo todo={todo} />
_12
if (todos)
_12
return <FlatList data={Object.values(todos)} renderItem={renderItem} style={styles.todos} />
_12
_12
return <></>
_12
})
observer is the suggested way of consuming observables for the best performance and safety.
It turns the entire component into an observing context - it automatically tracks observables for changes when get() is called, even from within hooks or helper functions.
This means, as long as realtime is enabled on the respective table, the component will automatically update when changes are made to the data!
Also, thanks to the persist and retry settings above, Legend-State will automatically retry to sync changes if the connection is lost.
To add a new todo from the application, you will need to generate a uuid locally to insert it into our todos observable. You can use the uuid package to generate a uuid. For this to work in React Native you will also need the react-native-get-random-values polyfill.
In your SupaLegend.ts file add the following:
_20
// [...]
_20
import 'react-native-get-random-values'
_20
import { v4 as uuidv4 } from 'uuid'
_20
// [...]
_20
_20
// Provide a function to generate ids locally
_20
const generateId = () => uuidv4()
_20
_20
export function addTodo(text: string) {
_20
const id = generateId()
_20
// Add keyed by id to the todos$ observable to trigger a create in Supabase
_20
todos$[id].assign({
_20
id,
_20
text,
_20
})
_20
}
_20
_20
export function toggleDone(id: string) {
_20
todos$[id].done.set((prev) => !prev)
_20
}
Now, in your App.tsx file, you can import the addTodo and toggleDone methods and call them when the user submits a new todo or checks off one:
_46
import { useState } from 'react'
_46
import { FlatList, StyleSheet, Text, TextInput, TouchableOpacity } from 'react-native'
_46
// [...]
_46
import { observer } from '@legendapp/state/react'
_46
import { addTodo, todos$ as _todos$, toggleDone } from './utils/SupaLegend'
_46
// [...]
_46
_46
// Emojis to decorate each todo.
_46
const NOT_DONE_ICON = String.fromCodePoint(0x1f7e0)
_46
const DONE_ICON = String.fromCodePoint(0x2705)
_46
_46
// The text input component to add a new todo.
_46
const NewTodo = () => {
_46
const [text, setText] = useState('')
_46
const handleSubmitEditing = ({ nativeEvent: { text } }) => {
_46
setText('')
_46
addTodo(text)
_46
}
_46
return (
_46
<TextInput
_46
value={text}
_46
onChangeText={(text) => setText(text)}
_46
onSubmitEditing={handleSubmitEditing}
_46
placeholder="What do you want to do today?"
_46
style={styles.input}
_46
/>
_46
)
_46
}
_46
_46
// A single todo component, either 'not done' or 'done': press to toggle.
_46
const Todo = ({ todo }: { todo: Tables<'todos'> }) => {
_46
const handlePress = () => {
_46
toggleDone(todo.id)
_46
}
_46
return (
_46
<TouchableOpacity
_46
key={todo.id}
_46
onPress={handlePress}
_46
style={[styles.todo, todo.done ? styles.done : null]}
_46
>
_46
<Text style={styles.todoText}>
_46
{todo.done ? DONE_ICON : NOT_DONE_ICON} {todo.text}
_46
</Text>
_46
</TouchableOpacity>
_46
)
_46
}
Since Legend-State utilizes supabase-js under the hood, you can use Supabase Auth and row level security to restrict access to the data.
For a tutorial on how to add user management to your Expo React Native application, refer to this guide.
Legend-State and Supabase are a powerful combination for building local-first applications. Legend-State pairs nicely with supabase-js, Supabase Auth and Supabase Realtime, allowing you to tap into the full power of the Supabase Stack while building fast and delightful applications that work across web and mobile platforms.
Want to learn more about Legend-State? Refer to their docs and make sure to follow Jay Meistrich on Twitter!