Configuration - FirstFlow

FirstFlow is configured almost entirely through the Supabase client and provider props you pass in code. The only environment variables it relies on are your Supabase keys and, optionally, an AI provider key for the server SDK. There is no FirstFlow server, so there are no service secrets, ports, or database URLs to manage.

Supabase

There are three values: a project URL and anon key (both browser-safe, used by the runtime) and a service-role key (server-only, used by @firstflow/runtime-server). The runtime takes plain strings you read them however your stack exposes env. The two browser-safe values must use your bundler’s client-env prefix so they reach the browser; the service-role key must never carry such a prefix.

Value	Browser-safe?	Next.js	Vite	Create React App	Node (server)
Project URL	yes	`NEXT_PUBLIC_SUPABASE_URL`	`VITE_SUPABASE_URL`	`REACT_APP_SUPABASE_URL`	`SUPABASE_URL`
`anon` key	yes	`NEXT_PUBLIC_SUPABASE_ANON_KEY`	`VITE_SUPABASE_ANON_KEY`	`REACT_APP_SUPABASE_ANON_KEY`
`service_role` key	no	`SUPABASE_SERVICE_ROLE_KEY`	`SUPABASE_SERVICE_ROLE_KEY`	`SUPABASE_SERVICE_ROLE_KEY`	`SUPABASE_SERVICE_ROLE_KEY`

// The name is your bundler's; the runtime just wants the string.
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,        // Next.js
  // import.meta.env.VITE_SUPABASE_URL,         // Vite
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
);

A client-env prefix (NEXT_PUBLIC_, VITE_, REACT_APP_) inlines a value into your browser bundle, where end users can read it. Only the URL and anon key may carry one. The service_role key bypasses Row Level Security keep it on the server with a plain name, and never commit it.

AI provider

Needed only if you wrap an LLM client with @firstflow/runtime-server or use the intent classifier. The widget, experiences, persistence, resume, and triggers all run without any AI key. FirstFlow reads no API key. It wraps an LLM client you construct, so the key comes from wherever you supply it there is no FIRSTFLOW-owned key variable. There are three ways to provide it:

Provider default env
Your own env name
OpenAI-compatible endpoint

Each provider SDK reads its own conventional variable. Set it and construct the client with no arguments:

ANTHROPIC_API_KEY=sk-ant-...     # the Anthropic SDK reads this
# or
OPENAI_API_KEY=sk-...            # the OpenAI SDK reads this

const ai = ff.wrap(new Anthropic());   // reads ANTHROPIC_API_KEY
const ai = ff.wrap(new OpenAI());       // reads OPENAI_API_KEY

Name the variable anything you like and pass it explicitly:

MY_CLAUDE_KEY=sk-ant-...

const ai = ff.wrap(new Anthropic({ apiKey: process.env.MY_CLAUDE_KEY }));
const ai = ff.wrap(new OpenAI({ apiKey: process.env.MY_OPENAI_KEY }));

For Ollama, vLLM, LM Studio, LocalAI, or a gateway, use createAIClient and pass the base URL + key explicitly (names are yours):

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=not-needed           # many local servers ignore this

import { createAIClient } from "@firstflow/runtime-server/aiclient";

const ai = createAIClient({
  baseURL: process.env.LLM_BASE_URL,
  apiKey: process.env.LLM_API_KEY ?? "not-needed",
  persistence,
});

openai is an optional peer dependency loaded only by this subpath install it when you use createAIClient. Anthropic-only deployments never pull it in.

In every case ff.wrap(...) / createAIClient(...) returns a normal client FirstFlow only observes the calls, it never owns the credentials. See the Server SDK.

Where the rest of the config lives

Most of what other tools put in environment variables, FirstFlow puts in code, because there is no server reading a .env:

Setting	Where it lives
Which experiences exist	`firstflow/experiences.json` in your repo
End-user identity	the `user` prop on `FirstflowProvider`
Persistence backend	the `persistence` prop (Supabase adapter or your own)
Intent branches, classifier model, hysteresis	arguments to `ff.classifyIntent(...)`
Capturing prompt/completion content	`captureContent` on `new Firstflow({...})`

Linking the front-end and back-end

user.id ties a person’s experiences (front-end) to their LLM activity (server SDK) pass the same one to both. The server SDK also takes a conversationId/sessionId, an id your own chat code owns, to group a transcript; FirstflowProvider does not use it. See Identity & auth.

Lock down table access with Row Level Security, then review Identity & auth and the production checklist.

​Supabase

​AI provider

​Where the rest of the config lives

​Linking the front-end and back-end

​Next

Supabase

AI provider

Where the rest of the config lives

Linking the front-end and back-end

Next