Quick Start

We’ll get Cuttlefish running in a Next.js app in 5 minutes.

Prerequisites

Before we begin, we’ll need:Node.js 20+ - Required for running the Cuttlefish dev server and our Next.js app.A Next.js app - Don’t have one? Create a new Next.js app:

npx create-next-app@latest

A local Postgres database - Don’t have one? Run Postgres with Docker:

docker run --name postgres -p 5432:5432 -e POSTGRES_PASSWORD=postgres -d postgres

A database table to query - Starting fresh? Create a sample todos table:

docker exec -i postgres psql -U postgres -d postgres -c "CREATE TABLE todos (id SERIAL PRIMARY KEY, title TEXT NOT NULL, completed BOOLEAN DEFAULT FALSE, created_at TIMESTAMPTZ DEFAULT NOW());"

Installation

Install Cuttlefish packages:

npm install @cuttlefish-sync/dev-server @cuttlefish-sync/core @cuttlefish-sync/react @cuttlefish-sync/raw-sql

Setup

We’ll wrap our app with CuttlefishProvider in app/layout.tsx:

import { CuttlefishProvider } from '@cuttlefish-sync/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <CuttlefishProvider serverUrl="ws://localhost:4000/socket">
          {children}
        </CuttlefishProvider>
      </body>
    </html>
  )
}

Start the dev server

In a separate terminal, start the Cuttlefish dev server:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres npx cuttlefish-dev-server start

We should see: Cuttlefish Engine running on http://localhost:4000

Your first live query

The useLiveQuery hook executes a SQL query and automatically updates our component when data changes in the database. It returns data, loading, and error states just like any async hook.Create app/page.tsx:

'use client'

import { sql } from '@cuttlefish-sync/raw-sql'
import { useLiveQuery } from '@cuttlefish-sync/react'

export default function Home() {
  const { data, loading, error } = useLiveQuery(
    sql`SELECT * FROM todos ORDER BY created_at DESC`
  )

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <div>
      <h1>My Todos</h1>
      <ul>
        {data?.map((todo) => (
          <li key={todo.id}>
            {todo.title} {todo.completed ? '✓' : ''}
          </li>
        ))}
      </ul>
    </div>
  )
}

Verify it works

Let’s open our Next.js app in the browser at http://localhost:3000. We should see “My Todos” with our existing todos (or an empty list).Now let’s see live updates in action. Open a new terminal and insert a todo directly into the database:

docker exec -i postgres psql -U postgres -d postgres -c "INSERT INTO todos (title, completed) VALUES ('Buy groceries', false);"

Watch the browser - the new todo appears instantly, with no page refresh.This is Cuttlefish’s core value: our UI stays synchronized with the database in real-time. Any change to the database - whether from another user, a background job, or a manual SQL command - appears immediately in all connected clients.

Next steps

Congratulations! We’ve built our first live-updating React app with Cuttlefish. Learn the concepts:

Understand how Cuttlefish works - Live Partial Replica architecture, Composable Sync, and more

Explore advanced patterns:

Use Kysely for type-safe queries - Get full TypeScript type safety with Kysely
Query local data only - Use useLocalLiveQuery for instant, zero-latency queries
Optimize with Composable Sync - Replicate once, query infinitely
Add authentication - Integrate with your existing auth system

API Reference:

useLiveQuery - Live query hook
useLocalLiveQuery - Local-only queries
replicateQuery - Manual replication control

​Quick Start

​Next steps

Quick Start

Next steps