@firstflow/nextjs

v0.0.2

Published

24 days ago

Firstflow platform Next.js SDK — surveys, experiences (messages, announcements, slots), and analytics with server-side configuration

0High
0Medium
0Low

aodat

tamimi-firstflow

firstflow nextjs react onboarding survey sdk

Firstflow Next.js SDK

Why Firstflow for Next.js?

Firstflow provides a first-class Next.js integration with server-side rendering, ensuring:

⚡ Zero Layout Shift — Pre-fetch config on the server for instant rendering
🌐 SEO Friendly — Server-rendered surveys and experiences
🔄 App Router Ready — Full support for Next.js 14+ App Router
📦 Server Components — Native server-side data fetching
🎯 Typed APIs — Full TypeScript support with autocompletion

Key Features

🚀 Server-Side Rendering — Pre-fetch agent configuration on the server
🎨 App Router Compatible — Works seamlessly with React Server Components
🔐 Secure by Default — API keys stay on the server
📊 Built-in Analytics — Jitsu-compatible event pipeline

Quick Start

1. Server-Side (app/layout.tsx)

import { getFirstflowConfig } from "@firstflow/nextjs/server";
import { FirstflowProvider } from "@firstflow/nextjs";

export default async function Layout({ children }: { children: React.ReactNode }) {
  // Fetch config on the server - no client-side fetch!
  const firstflowConfig = await getFirstflowConfig();

  return (
    <html>
      <body>
        <FirstflowProvider
          agentId={process.env.FIRSTFLOW_AGENT_ID!}
          initialSdkPayload={firstflowConfig}
        >
          {children}
        </FirstflowProvider>
      </body>
    </html>
  );
}

2. Client-Side (app/page.tsx)

"use client";

import { FirstflowWidget, useFirstflow } from "@firstflow/nextjs";

export default function Page() {
  const firstflow = useFirstflow();

  // Track analytics events
  firstflow.analytics.track("page_viewed", { path: "/" });

  return (
    <main>
      <h1>Welcome to Your App</h1>
      {/* Render Firstflow experiences */}
      <FirstflowWidget />
    </main>
  );
}

Installation

npm install @firstflow/nextjs

Requirements:

Next.js 14+
React 18+
React DOM 18+

Server-Side Configuration

Environment Variables

Create a .env.local file:

FIRSTFLOW_AGENT_ID=your_agent_id
FIRSTFLOW_API_KEY=your_api_key

Server API

`getFirstflowConfig()`

Fetches agent configuration server-side:

import { getFirstflowConfig } from "@firstflow/nextjs/server";

const config = await getFirstflowConfig();
// Returns SdkAgentConfigPayload for passing to FirstflowProvider

Advanced Server Usage

import { getFirstflowConfig, fetchSdkAgentConfig } from "@firstflow/nextjs/server";

// With custom options
const config = await fetchSdkAgentConfig({
  agentId: "custom-agent",
  apiKey: process.env.FIRSTFLOW_API_KEY,
});

Client-Side Integration

FirstflowProvider

| Prop | Type | Required | Description | |------|------|----------|-------------| | agentId | string | Yes | Your agent ID from dashboard | | initialSdkPayload | object | No | Server-fetched config | | user | UserContext | No | User identity and traits | | autoFetchAudienceMembership | boolean | No | Auto-fetch segments (default: true) | | fallback | ReactNode | No | Loading state | | onError | (error) => void | No | Error handler |

Core Features

SSR Data Fetching

The Next.js SDK provides server-side data fetching to eliminate loading states:

// app/layout.tsx - Server Component
import { getFirstflowConfig } from "@firstflow/nextjs/server";

export default async function Layout({ children }) {
  const config = await getFirstflowConfig(); // Server-side only!
  
  return (
    <FirstflowProvider initialSdkPayload={config}>
      {children}
    </FirstflowProvider>
  );
}

Surveys

Render interactive surveys in your chat:

import { useFirstflowSurvey, Survey } from "@firstflow/nextjs";

function ChatSurvey() {
  const { activeSurvey, isLoading } = useFirstflowSurvey();
  
  if (isLoading || !activeSurvey) return null;
  
  return (
    <Survey
      survey={activeSurvey}
      onComplete={(answers) => {
        console.log("Survey completed:", answers);
      }}
    />
  );
}

Experiences

Display messages, announcements, and tours:

import {
  FirstflowWidget,
  ExperienceMessageCard,
  ExperienceAnnouncementCard,
  useExperienceMessageNode,
  useExperienceAnnouncementNode,
} from "@firstflow/nextjs";

// Renders all eligible experiences
<FirstflowWidget />

// Or render specific types
<ExperienceMessageCard />
<ExperienceAnnouncementCard />
<ExperienceTourChrome />

Analytics

Full analytics support with server-side initializtion:

const firstflow = useFirstflow();

// Track events
firstflow.analytics.track("button_clicked", { source: "header" });

// Identify users
firstflow.analytics.identify("user_123", { plan: "pro" });

// Page views
firstflow.analytics.page("dashboard");

// Event constants
import {
  SURVEY_COMPLETED,
  EXPERIENCE_SHOWN,
  EXPERIENCE_CLICKED,
  CHAT_MESSAGE_SENT,
} from "@firstflow/nextjs";

API Reference

Server Exports (`@firstflow/nextjs/server`)

| Export | Description | |--------|-------------| | getFirstflowConfig() | Fetch agent config server-side | | fetchSdkAgentConfig() | Custom fetch with options |

Client Exports (`@firstflow/nextjs`)

| Category | Exports | |----------|---------| | Provider | FirstflowProvider, createFirstflowApp | | Hooks | useFirstflow, useFirstflowSelector, useFirstflowSurvey, useFirstflowFeedback, useFirstflowIssueReporter | | Components | FirstflowWidget, Survey, ExperienceMessageCard, ExperienceAnnouncementCard, ExperienceTourChrome | | Analytics | track, identify, page (via useFirstflow) |

Types

import type {
  FirstflowInstance,
  CreateFirstflowOptions,
  UserContext,
  SdkAgentConfigPayload,
  SurveyExperience,
} from "@firstflow/nextjs";

Best Practices

✅ Do

Use getFirstflowConfig() in server components — Prevents client-side fetch waterfalls
Pass initialSdkPayload to provider — Eliminates loading states
Keep API keys in environment variables — Never expose on client
Use typed constants for events — SURVEY_COMPLETED, EXPERIENCE_SHOWN

❌ Don't

Don't call server functions from client — Use only in Server Components
Don't pass raw API keys to client — Use initialSdkPayload pattern
Don't create multiple providers — One per app only

Performance

Server-fetched config is cached during request
Use refreshConfig() for runtime updates
Audience membership replaced (not merged) after fetch

Security

Enterprise-grade security for Next.js applications:

🔐 Server-Side Keys — API keys never exposed to client
✅ SOC 2 Compliant — Enterprise security posture
🇪🇺 GDPR Ready — Full DPA available
🛡️ No PII Storage — User data is transient

Support

📖 Documentation: docs.firstflow.app
💬 Discord: Join our community
🐛 Issue Tracker: Report bugs
📧 Enterprise: Contact sales

License

This SDK is licensed under the MIT License.

MIT License

Copyright (c) 2024 Firstflow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.