Stream real-time data to your React app from your existing Postgres database.

Request Feature · Report Bug

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.

Introduction

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

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.

"Look at all the things I'm not doing."

• ✅ 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

Features

• @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

Getting started

1. Install the Solarflare CLI:

   npm install -g @solarflare/solarflared

2. 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 your postgresql.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 the rls 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.

3. Run the Solarflare server:

   solarflare start

   This will start the Solarflare server on http://localhost:54321. It reads the solarflare.json configuration file.

4. Install the Solarflare client in your frontend project:

    npm install @solarflare/client

5. Generate types for your tables:

   solarflare codegen

6. 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, or layout.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.

7. 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>
       )
   }

Optimistic updates

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>
  );
};