Next.js

@firstflow/runtime works in any React setup. In Next.js (App Router) the only rules are the usual ones: the provider is a client component, and your server-only Supabase key never crosses into the browser.

Provider in a client component

The provider uses hooks and localStorage, so it must run on the client. Wrap it in a "use client" component and mount that in your layout.

app/firstflow-provider.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!,
);

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

app/layout.tsx

import { Firstflow } from "./firstflow-provider";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Firstflow>{children}</Firstflow>
      </body>
    </html>
  );
}

Environment variables

Only the browser-safe pair carries the NEXT_PUBLIC_ prefix. The server SDK’s service_role key must not:

NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...   # server-only use in route handlers, never in client components

Wrapping LLM calls in route handlers

Use the server SDK inside route handlers (or server actions), where the service_role key is safe:

app/api/chat/route.ts

import { Firstflow } from "@firstflow/runtime-server";
import { createSupabaseLLMPersistence } from "@firstflow/runtime-server/supabase";
// build the service-role Supabase client here, server-side only

Notes

The browser runtime has no conversation id. Link the two sides by passing the same user.id to the provider and to your server calls; the server-side conversationId/sessionId is owned by your own chat code.
Identify users from your auth in the client component (user={...}); omit it for anonymous visitors.

Browser SDK

Server SDK

Advanced

Provider in a client component

Environment variables

Wrapping LLM calls in route handlers

Notes

​Provider in a client component

​Environment variables

​Wrapping LLM calls in route handlers

​Notes

Provider in a client component

Environment variables

Wrapping LLM calls in route handlers

Notes