Instant local-first

In this introduction, we're going to walk through local-first development and the ElectricSQL system. You're going to see what's good and different about it, explore some of the challenges and see how ElectricSQL solves them.

Along the way, we hope you'll be convinced to stop building cloud-first systems and switch to #lo-fi ⚡ as your preferred development approach instead.

Code along

This is an interactive demo. You can play with the widgets in the browser and you can play with the source code for the widgets in the live editor as you go. You can also find all the source code in the examples/introduction folder of the main electric‑sql/electric repo.

note

If you just want the fastest way to start coding, jump to the Quickstart instead.

Let's get started

Electric is a system for building local-first apps. These apps interact directly with a local, embedded database. This is consistently fast compared with going over the network.

Below, there are two embedded demo apps:

1. local-first where the application code talks to a local embedded database
2. cloud-first where the application code talks to a cloud service

Have a play with the interfaces and see how responsive they feel.

Live Editor

const newItem = (demo) => { return { id: genUUID(), inserted_at: `${Date.now()}`, demo_id: demo.id, demo_name: demo.name, electric_user_id: demo.electric_user_id, } } // The local-first component talks directly to the embedded SQLite database // and naturally stays in sync. const LocalFirst = () => { const { db } = useElectric() const { demo } = useDemoContext() const { results } = useLiveQuery( db.items.liveMany({ where: { demo_name: demo.name, electric_user_id: demo.electric_user_id, }, orderBy: { inserted_at: 'asc', }, take: 24, }), ) // This next block is just to time the initial fetch latency. const [t1] = useState(Date.now()) const [fetchLatency, setFetchLatency] = useState(-1) useEffect(() => { if (results === undefined || fetchLatency > 0) { return } setFetchLatency(Date.now() - t1) }, [results]) const add = async () => { await db.items.create({ data: newItem(demo), }) } const clear = async () => { await db.items.deleteMany({ where: { demo_name: demo.name, electric_user_id: demo.electric_user_id, }, }) } if (results === undefined || fetchLatency < 0) { return null } return ( <LatencyWidget add={add} clear={clear} items={results} initialLatency={fetchLatency} itemColor="electric-green" title="Local-first" /> ) } // The cloud-first component talks to the backend using an API client and // manually updates the local state (if the request is successful). const CloudFirst = () => { const { demo } = useDemoContext() const [results, setResults] = useState() const [fetchLatency, setFetchLatency] = useState(-1) const mountedRef = useRef(false) useEffect(() => { mountedRef.current = true return () => { mountedRef.current = false } }, []) useEffect(() => { const loadItems = async () => { const { elapsed, result } = await timeResolution( api.getItems({ demo_id: demo.id }), ) if (!mountedRef.current) { return } const items = result !== undefined ? result : [] setFetchLatency(elapsed) setResults(items) } loadItems() }, []) const add = async () => { const item = newItem(demo) const savedItem = await api.postItem({ data: item, }) if (!mountedRef.current) { return } if (savedItem === undefined) { return } setResults([...results, savedItem]) } const clear = async () => { const ok = await api.deleteItem({ data: { demo_id: demo.id, }, }) if (!mountedRef.current || !ok) { return } setResults([]) } if (results === undefined) { return null } return ( <LatencyWidget add={add} clear={clear} items={results.slice(0, 24)} title="Cloud-first" initialLatency={fetchLatency} itemColor="script-red" disableWhenInProgress={true} /> ) } const Demo = () => { return ( <div className="grid grid-cols-1 sm:grid-cols-2 gap-6" data-testid="local-first-instant-demo"> <div className="px-3 md:px-4" data-testid="local-first"> <App dbName="user1" demoName="local-first" bootstrapItems={4}> <LocalFirst /> </App> </div> <div className="px-3 md:px-4" data-testid="cloud-first"> <CloudApp demoName="cloud-first" bootstrapItems={4}> <CloudFirst /> </CloudApp> </div> </div> ) } render(<Demo />)

const newItem = (demo) => {
  return {
    id: genUUID(),
    inserted_at: `${Date.now()}`,
    demo_id: demo.id,
    demo_name: demo.name,
    electric_user_id: demo.electric_user_id,
  }
}

// The local-first component talks directly to the embedded SQLite database
// and naturally stays in sync.
const LocalFirst = () => {
  const { db } = useElectric()
  const { demo } = useDemoContext()

  const { results } = useLiveQuery(
    db.items.liveMany({
      where: {
        demo_name: demo.name,
        electric_user_id: demo.electric_user_id,
      },
      orderBy: {
        inserted_at: 'asc',
      },
      take: 24,
    }),
  )

  // This next block is just to time the initial fetch latency.
  const [t1] = useState(Date.now())
  const [fetchLatency, setFetchLatency] = useState(-1)
  useEffect(() => {
    if (results === undefined || fetchLatency > 0) {
      return
    }

    setFetchLatency(Date.now() - t1)
  }, [results])

  const add = async () => {
    await db.items.create({
      data: newItem(demo),
    })
  }

  const clear = async () => {
    await db.items.deleteMany({
      where: {
        demo_name: demo.name,
        electric_user_id: demo.electric_user_id,
      },
    })
  }

  if (results === undefined || fetchLatency < 0) {
    return null
  }

  return (
    <LatencyWidget
      add={add}
      clear={clear}
      items={results}
      initialLatency={fetchLatency}
      itemColor="electric-green"
      title="Local-first"
    />
  )
}

// The cloud-first component talks to the backend using an API client and
// manually updates the local state (if the request is successful).
const CloudFirst = () => {
  const { demo } = useDemoContext()
  const [results, setResults] = useState()
  const [fetchLatency, setFetchLatency] = useState(-1)
  const mountedRef = useRef(false)

  useEffect(() => {
    mountedRef.current = true

    return () => {
      mountedRef.current = false
    }
  }, [])

  useEffect(() => {
    const loadItems = async () => {
      const { elapsed, result } = await timeResolution(
        api.getItems({ demo_id: demo.id }),
      )

      if (!mountedRef.current) {
        return
      }

      const items = result !== undefined ? result : []

      setFetchLatency(elapsed)
      setResults(items)
    }

    loadItems()
  }, [])

  const add = async () => {
    const item = newItem(demo)
    const savedItem = await api.postItem({
      data: item,
    })

    if (!mountedRef.current) {
      return
    }

    if (savedItem === undefined) {
      return
    }

    setResults([...results, savedItem])
  }

  const clear = async () => {
    const ok = await api.deleteItem({
      data: {
        demo_id: demo.id,
      },
    })

    if (!mountedRef.current || !ok) {
      return
    }

    setResults([])
  }

  if (results === undefined) {
    return null
  }

  return (
    <LatencyWidget
      add={add}
      clear={clear}
      items={results.slice(0, 24)}
      title="Cloud-first"
      initialLatency={fetchLatency}
      itemColor="script-red"
      disableWhenInProgress={true}
    />
  )
}

const Demo = () => {
  return (
    <div className="grid grid-cols-1 sm:grid-cols-2 gap-6" data-testid="local-first-instant-demo">
      <div className="px-3 md:px-4" data-testid="local-first">
        <App dbName="user1" demoName="local-first" bootstrapItems={4}>
          <LocalFirst />
        </App>
      </div>
      <div className="px-3 md:px-4" data-testid="cloud-first">
        <CloudApp demoName="cloud-first" bootstrapItems={4}>
          <CloudFirst />
        </CloudApp>
      </div>
    </div>
  )
}

render(<Demo />)

As you can see, the local-first one is consistently fast to interact with. There's no lag or loading spinners. Just instant reactivity.

The cloud-first one may feel fast or slow, depending on your network connection. If you have developer tools available, you can simulate a poor connection by opening up your browser console, going to the network tab and set throttling to "Slow 3G" or "Offline". How does the cloud-first app feel now?

Ultimately, if you have the network on your interaction path, the quality of your users' experience depends on their connectivity. Whereas with local-first, everything is instant, there are no loading spinners and you own your own UX and availability.

---

Instant reactivity is one aspect of local-first. Another is realtime multi-user collaboration. Let's explore that next »