Stream real-time data to your React app from your existing Postgres database.
Warning
This code is in active development and is not yet production-ready.
If you're excited by what we're building, we're looking for design partners - contact us if you want early access to Solarflare.
Join our waitlist to be notified when we launch for production use.
Solarflare is a lightweight system allowing you to stream realtime data to your React app from your existing Postgres database.
Solarflare is distributed as two packages:
@solarflare/solarflared
(npm) — daemon process to manage client connections and perform partial data replication from Postgres to clients@solarflare/client
(npm) — fully-typed client for TypeScript React frontends.
Installation is as simple as:
solarflare init
- select which Postgres tables to make live
- configure auth so that only authorised rows are replicated to clients
solarflare start
- A few lines of React code with
@solarflare/client
import { useTable } from '@solarflare/client'
const Todos = () => {
const { data, isLoading } = useTable("todos") // <- fully-typed API
return (
<div>
{data.map(todo => <Todo key={todo.id} todo={todo}>)}
</div>
)
}
Now, if a row is added, deleted or edited in Postgres, the Todos
component will automatically and instantly re-render with the changes. You don't have to do anything else.
- ✅ Don't think about the network
- ✅ Don't configure WebSockets or invent a communication protocol
- ✅ Don't figure out how to replicate just the relevant rows
- ✅ Don't spend days learning about the guts of Postgres logical replication
- ✅ Don't get a PhD in fault-tolerant distributed systems
- ✅ Don't be a Postgres database admin
-
@solarflare/solarflared
— daemon process to manage client connections and perform partial data replication from Postgres to clients -
@solarflare/client
— fully-typed client for TypeScript React frontends - Live, declarative view of your existing Postgres tables with minimal setup
- JWT-based auth for partial replication
- Optimistic update API
- In-browser local persistent storage
-
Install the Solarflare CLI:
npm install -g @solarflare/solarflared
-
Initialize Solarflare in your backend project:
solarflare init
This command will interactively allow you to configure which tables you want to expose to your frontend, and ensures that your Postgres installation works with Solarflare. In particular, you need to have logical replication enabled with
wal_level = logical
in yourpostgresql.conf
file (this requires a Postgres restart).Each table can have row-level security configured. Currently, this works by nominating a column as the
rls
column and a JWT claim to use for filtering. When a user on your frontend loads a table from Solarflare, they will only see rows where therls
column matches the claim in their JWT.The command generates a
solarflare.json
file in your project root, which you can commit to your version control system. -
Run the Solarflare server:
solarflare start
This will start the Solarflare server on
http://localhost:54321
. It reads thesolarflare.json
configuration file. -
Install the Solarflare client in your frontend project:
npm install @solarflare/client
-
Generate types for your tables:
solarflare codegen
-
Setup a
SolarflareProvider
in your React app.This needs to be somewhere high up in your component tree, so that all components that use Solarflare are descendants of it. If your project is a Next.js app, you could put it in
_app.tsx
, orlayout.tsx
.import { SolarflareProvider } from "@solarflare/client"; const App = ({ Component, pageProps }) => { const usersJwt = "..."; return ( <SolarflareProvider jwt={usersJwt} solarflareUrl="http://localhost:54321" > <Component {...pageProps} /> </SolarflareProvider> ); };
The
jwt
prop is the JWT that Solarflare will use to filter rows in your tables. -
Use the
useTable
hook in your components to get live data from your Postgres tables.import { createSolarflare, type DB } from '@solarflare/client' const { useTable } = createSolarflare<DB>() const Todos = () => { const { data, isLoading } = useTable("todos"); if (isLoading) return <div>Loading...</div> return ( <div> {data.map(todo => <Todo key={todo.id} todo={todo}>)} </div> ) }
Solarflare supports optimistic updates. Our philosophy is one of pragmatism. We don't attempt to solve the general case of conflict resolution, or be a full-blown ORM where you just edit the values of object fields and expect everything to happen by magic.
Instead, for live changing data, the model we encourage is:
- You have a server which performs writes
- The server exposes an API which you can call to perform writes (e.g. REST, GraphQL, tRPC)
- When you render the page, you fetch the data via Solarflare and get a declarative view to render in a natural way
- When a user does an action, you call your (non-Solarflare) API to request the change
- Your server performs whatever complex validation, authorization or conflict resolution logic is necessary
- Your server writes the change to the database
- The database, being the source of truth for the state of your data, pushes changes out via Solarflare to everybody who needs to know
- Meanwhile, your frontend client can optimistically render the updated value with a couple of lines of Javascript. When the ratified change comes back via Solarflare, the optimistic update is replaced with the real data
Here's how you do an optimistic update with Solarflare:
const Todos = () => {
const { data, optimistic } = useTable("todos");
const updateTodo = async (id: number, text: string) => {
// Perhaps do some client-side validation here...
// Optimistically update the UI
const { rollback } = optimistic({
action: "update",
id,
data: { text },
});
const res = /* call your normal API here */;
// If the server responds with an error, roll back the optimistic update
if (res.error) {
rollback();
}
};
return (
<div>
{data.map((todo) => (
<Todo key={todo.id} todo={todo} updateTodo={updateTodo} />
))}
</div>
);
};