Quickstart - FirstFlow

This is the whole setup: install the packages, apply the migrations to a Supabase project you own, author one experience in your repo, mount the provider, and (optionally) wrap your LLM client. The runtime evaluates everything in the browser, so there is no FirstFlow service to run.

Prerequisites

Node 18+ and pnpm 9 (the repo’s package manager).
git to clone the repo.
A Supabase project free tier is fine. Create one at supabase.com/dashboard.

You consume FirstFlow by cloning the repo and building your app inside its workspace. The packages aren’t published to npm; your app references them locally with workspace:*.

Steps

Fork, clone, and build

Fork firstflow-oss (so you can commit your own app into it), clone your fork, install, and build the packages once.

git clone https://github.com/<you>/firstflow-oss
cd firstflow-oss
pnpm install
pnpm build      # builds @firstflow/runtime, runtime-server, config-schema

Add your app to the workspace

Scaffold your app in a new folder inside the repo with your stack’s usual tool:

Next.js
Vite + React

pnpm create next-app@latest apps/web

pnpm create vite@latest apps/web -- --template react-ts

Add its folder to the workspace and reference the packages with workspace:*:

pnpm-workspace.yaml

packages:
  - "packages/*"
  - "apps/*"            # add the folder your app lives in

apps/web/package.json

{
  "dependencies": {
    "@firstflow/runtime": "workspace:*",
    "@firstflow/runtime-server": "workspace:*",
    "@firstflow/config-schema": "workspace:*",
    "@supabase/supabase-js": "^2.45.0"
  }
}

Then run pnpm install from the repo root. Only @firstflow/runtime + @supabase/supabase-js are required; add @firstflow/runtime-server for LLM observability.

workspace:* only resolves inside this monorepo that’s why your app lives here. Re-run pnpm build after editing any package so your app picks up the change.

Set up Supabase

Create a project, then paste packages/config-schema/supabase/schema.sql into the Supabase SQL editor and run it once one file creates the whole schema. Full walkthrough in Set up Supabase.Then put the keys in your environment. Three values: the project URL and anon key are public (browser-safe); the service_role key is server-only. The variable names depend on your bundler public values must carry its client-env prefix:

Next.js
Vite + React
Create React App

.env.local

NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...        # server-only no NEXT_PUBLIC_ prefix

.env

VITE_SUPABASE_URL=https://xxxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJ...
# service_role key lives on your server only never in a VITE_ var

.env

REACT_APP_SUPABASE_URL=https://xxxxx.supabase.co
REACT_APP_SUPABASE_ANON_KEY=eyJ...
# service_role key lives on your server only never in a REACT_APP_ var

The NEXT_PUBLIC_ / VITE_ / REACT_APP_ prefix is just how each bundler exposes a value to the browser. The runtime itself takes plain strings see Configuration.

Author your first experience

Create firstflow/experiences.json in your repo. This file is your source of truth it is versioned in git and imported at build time.

firstflow/experiences.json

[
  {
    "id": "exp_welcome",
    "name": "Welcome",
    "type": "guide",
    "status": "active",
    "trigger": { "on": "page_load", "delay": 1 },
    "frequency": "once_per_user",
    "steps": [
      {
        "id": "hi",
        "type": "message",
        "title": "Hello",
        "content": "Welcome to my app!",
        "cta": "Get started"
      },
      { "id": "done", "type": "thank_you", "title": "You're all set", "confetti": true }
    ]
  }
]

The full step and action reference is in config-schema/SCHEMA.md.

Mount the provider and widget

@firstflow/runtime is plain React it works in any stack. Wrap your app once; only how you read the env differs. The default Supabase persistence adapter ships with @firstflow/runtime/supabase.

Next.js (App Router)
Vite + React

app/firstflow.tsx

"use client";
import "@firstflow/runtime/styles.css";
import { FirstflowProvider, FirstflowWidget } from "@firstflow/runtime";
import { createSupabasePersistence } from "@firstflow/runtime/supabase";
import { createClient } from "@supabase/supabase-js";
import experiences from "@/firstflow/experiences.json";

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
);
const persistence = createSupabasePersistence(supabase);

export function Firstflow({ children }: { children: React.ReactNode }) {
  return (
    <FirstflowProvider experiences={experiences} persistence={persistence}>
      {children}
      <FirstflowWidget />
    </FirstflowProvider>
  );
}

Mount <Firstflow> in your root layout. The provider is a client component (it uses hooks + localStorage). See Next.js.

App.tsx

import "@firstflow/runtime/styles.css";
import { FirstflowProvider, FirstflowWidget } from "@firstflow/runtime";
import { createSupabasePersistence } from "@firstflow/runtime/supabase";
import { createClient } from "@supabase/supabase-js";
import experiences from "./firstflow/experiences.json";

const supabase = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY,
);
const persistence = createSupabasePersistence(supabase);

export default function App() {
  return (
    <FirstflowProvider experiences={experiences} persistence={persistence}>
      <YourApp />
      <FirstflowWidget />
    </FirstflowProvider>
  );
}

Pass user={{ id, traits }} from your own auth for signed-in users. It’s optional omit it and the runtime uses a stable per-browser anonymous id so caps and resume still work.

(Optional) Observe your LLM calls

@firstflow/runtime-server is framework-agnostic Node set it up once with your server-only service-role key, then wrap your LLM client wherever you call it. The setup is identical across backends:

firstflow.server.ts

import { Firstflow } from "@firstflow/runtime-server";
import { createSupabaseLLMPersistence } from "@firstflow/runtime-server/supabase";
import { createClient } from "@supabase/supabase-js";
import Anthropic from "@anthropic-ai/sdk";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!, // server-only, bypasses RLS
);
export const ff = new Firstflow({
  persistence: createSupabaseLLMPersistence(supabase),
  captureContent: true,
});
export const ai = ff.wrap(new Anthropic());

Then call it from your handler:

Next.js route handler
Express
Hono

app/api/chat/route.ts

import { ai } from "@/firstflow.server";

export async function POST(req: Request) {
  const { userId, sessionId, message } = await req.json();
  const reply = await ai.messages.create({
    model: "claude-haiku-4-5",
    messages: [{ role: "user", content: message }],
    firstflow: { userId, sessionId },   // sessionId = the shared conversation id
  } as any);
  return Response.json({ reply });
}

import { ai } from "./firstflow.server";

app.post("/api/chat", async (req, res) => {
  const { userId, sessionId, message } = req.body;
  const reply = await ai.messages.create({
    model: "claude-haiku-4-5",
    messages: [{ role: "user", content: message }],
    firstflow: { userId, sessionId },
  } as any);
  res.json({ reply });
});

import { ai } from "./firstflow.server";

app.post("/api/chat", async (c) => {
  const { userId, sessionId, message } = await c.req.json();
  const reply = await ai.messages.create({
    model: "claude-haiku-4-5",
    messages: [{ role: "user", content: message }],
    firstflow: { userId, sessionId },
  } as any);
  return c.json({ reply });
});

Each call records a row in firstflow_llm_calls. See the Server SDK for traces, intent classification, and bring-your-own OpenAI-compatible clients.

Run it

Start your app. The welcome experience auto-fires after one second.

pnpm dev

Run through it, then check Supabase firstflow_flow_runs has a completed row.

Verify

A working setup shows three things:

The widget appears in the corner and advances through your experience.
firstflow_flow_runs gains a row per run (in-progress, then completed/dismissed).
If you wrapped an LLM client, firstflow_llm_calls gains a row per call.

If the widget never appears, confirm the experience status is "active" and the Supabase keys are set. If progress never persists, check the migrations are applied and Row Level Security allows the write.

Set up Supabase

Create the project and apply the migrations in order.

Configuration

Every environment variable FirstFlow reads.

Identity & auth

How user.id and anonymous visitors work.

Production

RLS, key hygiene, and backups.

​Prerequisites

​Steps

​Verify

​Next

Set up Supabase

Configuration

Identity & auth

Production

Prerequisites

Steps

Verify

Next