@syncagent/nextjs

@syncagent/nextjs

Next.js SDK for SyncAgent — server-safe helpers that keep your database connection string out of the browser bundle.

Works with MongoDB, PostgreSQL, MySQL, SQLite, SQL Server, and Supabase.

Get Your API Key

• Sign up for a free account
• Go to your Dashboard → New Project → choose your database type
• Copy your API key (starts with sa_)

Every new project gets a 14-day trial with 500 free requests — no credit card required. After the trial, you get 100 free requests/month on the Free plan.

Install

npm install @syncagent/nextjs @syncagent/js @syncagent/react

Why Use This Instead of @syncagent/react?

The @syncagent/nextjs package provides createServerConfig() which lets you safely pass your database connection string from Server Components — it never reaches the browser bundle. All config options from @syncagent/js are supported.

Quick Start

// app/dashboard/page.tsx — Server Component (no "use client")
import { createServerConfig } from "@syncagent/nextjs/server";
import { SyncAgentChat } from "@syncagent/nextjs";
import { getServerSession } from "next-auth";

export default async function DashboardPage() {
  const session = await getServerSession();

  const config = createServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    filter: { organizationId: session.user.orgId },
    operations: session.user.isAdmin
      ? ["read", "create", "update", "delete"]
      : ["read"],
  });

  return (
    <SyncAgentChat
      config={config}
      persistKey={session.user.id}
      accentColor="#6366f1"
      context={{ userId: session.user.id, page: "dashboard" }}
    />
  );
}

From Environment Variables

import { createServerConfigFromEnv } from "@syncagent/nextjs/server";

// Reads SYNCAGENT_KEY and DATABASE_URL automatically
const config = createServerConfigFromEnv({
  filter: { orgId: session.user.orgId },
  language: "French",
});

# .env.local
SYNCAGENT_KEY=sa_your_api_key
DATABASE_URL=mongodb+srv://user:pass@cluster/db

All Config Options

createServerConfig accepts all SyncAgentConfig options:

Option	Type	Required	Description
apiKey	string	✅	Your SyncAgent API key
connectionString	string	✅*	Your database URL — stays on the server. *Optional when toolsOnly: true.
filter	Record<string,any>	—	Mandatory query filter for multi-tenancy
operations	string[]	—	Restrict operations for this session
toolsOnly	boolean	—	Disables all DB tools — agent only uses custom tools
systemInstruction	string	—	Custom agent instructions — personality, tone, rules
confirmWrites	boolean	—	Ask for confirmation before writes
language	string	—	Language the agent responds in (e.g. "French")
maxResults	number	—	Default max records per query (default 50)
sensitiveFields	string[]	—	Fields to mask in responses
autoDetectPage	boolean	—	Auto-detect page from URL (default true)
baseUrl	string	—	Override API URL (dev only)

Full Example — Multi-tenant SaaS

// app/app/[orgSlug]/page.tsx — Server Component
import { createServerConfig } from "@syncagent/nextjs/server";
import { SyncAgentChat } from "@syncagent/nextjs";
import { getSession } from "@/lib/auth";
import { getOrganization } from "@/lib/db";

export default async function AppPage({ params }: { params: { orgSlug: string } }) {
  const session = await getSession();
  const org = await getOrganization(params.orgSlug);

  const config = createServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    filter: { organizationId: org.id },
    operations: session.user.role === "admin"
      ? ["read", "create", "update", "delete"]
      : ["read"],
    systemInstruction: `You are the AI assistant for ${org.name}. Be professional and helpful.`,
    language: org.language || "English",
    confirmWrites: true,
    maxResults: 25,
    sensitiveFields: ["ssn", "salary", "password"],
  });

  return (
    <SyncAgentChat
      config={config}
      persistKey={`${org.id}-${session.user.id}`}
      title={`${org.name} AI`}
      accentColor={org.brandColor}
      context={{ userId: session.user.id, userRole: session.user.role, orgName: org.name }}
    />
  );
}

Tools-only Mode

// Server Component
import { createServerConfig } from "@syncagent/nextjs/server";
import { ChatWithTools } from "./chat-with-tools";

export default async function Page() {
  const config = createServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    toolsOnly: true,
    systemInstruction: "You are a product search assistant.",
  });
  return <ChatWithTools serverConfig={config} />;
}

// app/dashboard/chat-with-tools.tsx — "use client"
import { SyncAgentChat } from "@syncagent/nextjs";

export function ChatWithTools({ serverConfig }) {
  return (
    <SyncAgentChat
      config={{
        ...serverConfig,
        tools: {
          searchProducts: {
            description: "Search products",
            inputSchema: { query: { type: "string" } },
            execute: async ({ query }) => {
              const res = await fetch(`/api/products?q=${query}`);
              return res.json();
            },
          },
        },
      }}
    />
  );
}

Customer Agent Mode

The createCustomerServerConfig server helper configures customer agent mode from a Server Component. It validates that externalUserId is provided — customer mode is automatically enabled when externalUserId is present.

Server Component

// app/support/page.tsx — Server Component
import { createCustomerServerConfig } from "@syncagent/nextjs/server";
import { getServerSession } from "next-auth";
import { CustomerSupportWidget } from "./customer-support-widget";

export default async function SupportPage() {
  const session = await getServerSession();

  const config = createCustomerServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    externalUserId: session.user.id,
    filter: { organizationId: session.user.orgId },
  });

  return <CustomerSupportWidget config={config} />;
}

Client Component

// app/support/customer-support-widget.tsx — "use client"
"use client";

import { useCustomerChat } from "@syncagent/nextjs";
import { SyncAgentClient } from "@syncagent/nextjs";
import type { SyncAgentConfig } from "@syncagent/js";

export function CustomerSupportWidget({ config }: { config: SyncAgentConfig }) {
  const client = new SyncAgentClient(config);

  const {
    messages,
    sendMessage,
    isLoading,
    isEscalated,
    isResolved,
    welcomeMessage,
    rateConversation,
  } = useCustomerChat({ client });

  return (
    <div>
      {welcomeMessage && <p>{welcomeMessage}</p>}
      {messages.map((msg, i) => (
        <div key={i}>{msg.role}: {msg.content}</div>
      ))}
      {isEscalated && <p>You have been connected to a human agent.</p>}
      {isResolved && (
        <div>
          <p>Conversation resolved.</p>
          <button onClick={() => rateConversation(5)}>Rate 5 ⭐</button>
        </div>
      )}
      <input
        onKeyDown={(e) => {
          if (e.key === "Enter") sendMessage(e.currentTarget.value);
        }}
        disabled={isLoading}
      />
    </div>
  );
}

externalUserId Requirement

The externalUserId option is required when using createCustomerServerConfig. Omitting it throws an error:

Error: @syncagent/nextjs: externalUserId is required for customer mode

This ID scopes conversations to a specific customer and should always come from an authenticated session (e.g. session.user.id).

Re-exported Hook

useCustomerChat is re-exported from @syncagent/nextjs for convenience — no need to install @syncagent/react separately:

import { useCustomerChat } from "@syncagent/nextjs";

Customer Chat

The <SyncAgentCustomerChat> component is a pre-built, drop-in customer support widget with guest identification, real-time messaging, escalation display, and satisfaction rating. In Next.js, you use a Server Component to create the config (keeping secrets out of the browser) and pass it to a Client Component that renders the widget.

Server Component + Client Component Pattern

// app/support/page.tsx — Server Component
import { createCustomerServerConfig } from "@syncagent/nextjs/server";
import { getServerSession } from "next-auth";
import { CustomerChat } from "./customer-chat";

export default async function SupportPage() {
  const session = await getServerSession();

  const config = createCustomerServerConfig({
    apiKey: process.env.SYNCAGENT_API_KEY!,
    connectionString: process.env.SYNCAGENT_CONNECTION_STRING!,
    externalUserId: session.user.id,
    filter: { organizationId: session.user.orgId },
  });

  return <CustomerChat config={config} />;
}

// app/support/customer-chat.tsx — Client Component
"use client";

import { SyncAgentCustomerChat } from "@syncagent/nextjs";
import type { SyncAgentConfig } from "@syncagent/nextjs";

export function CustomerChat({ config }: { config: SyncAgentConfig }) {
  return (
    <SyncAgentCustomerChat
      config={config}
      title="Support"
      subtitle="We're here to help"
      accentColor="#6366f1"
      darkMode={false}
      onEscalated={() => console.log("Escalated to human agent")}
      onResolved={(id) => console.log("Resolved:", id)}
    />
  );
}

Using createServerConfigFromEnv()

For simpler setups, read credentials from environment variables automatically:

// app/support/page.tsx — Server Component
import { createServerConfigFromEnv } from "@syncagent/nextjs/server";
import { CustomerChat } from "./customer-chat";

export default async function SupportPage() {
  // Reads SYNCAGENT_KEY and DATABASE_URL (or SYNCAGENT_CONNECTION_STRING) from env
  const config = createServerConfigFromEnv({
    customerMode: true,
    externalUserId: "user_123",
  });

  return <CustomerChat config={config} />;
}

# .env.local
SYNCAGENT_KEY=sa_your_api_key
SYNCAGENT_CONNECTION_STRING=mongodb+srv://user:pass@cluster/db

createServerConfigFromEnv() reads SYNCAGENT_KEY and DATABASE_URL (or SYNCAGENT_CONNECTION_STRING) automatically. Pass any additional options as overrides.

Environment Variables

Variable	Description
SYNCAGENT_KEY	Your SyncAgent API key (starts with sa_)
DATABASE_URL	Database connection string (primary)
SYNCAGENT_CONNECTION_STRING	Database connection string (alternative)

Never use the NEXT_PUBLIC_ prefix for these variables — they contain secrets that must stay on the server.

Props Reference

The <SyncAgentCustomerChat> component accepts all the same props as the React package version. See the @syncagent/react documentation for the full props table, theming options, and accessibility details.

Key props when used with server config:

Prop	Type	Default	Description
config	SyncAgentConfig	—	Server config from createCustomerServerConfig() or createServerConfigFromEnv()
mode	"floating" | "inline"	"floating"	Floating toggle button or embedded inline panel
position	"bottom-right" | "bottom-left"	"bottom-right"	Position of the floating widget (floating mode only)
defaultOpen	boolean	false	Whether the floating panel starts open (floating mode only)
title	string	"Customer Support"	Header title text (max 100 chars)
subtitle	string	"How can we help you?"	Header subtitle text (max 200 chars)
placeholder	string	"Type your message..."	Input placeholder text (max 150 chars)
accentColor	string	"#6366f1"	Primary accent color (hex, rgb, or hsl)
darkMode	boolean	false	Enable dark mode color scheme
pusherKey	string	—	Pusher app key for real-time human agent messages
onEscalated	() => void	—	Called when conversation is escalated
onResolved	(id: string) => void	—	Called when conversation is resolved
onGuestIdentified	(identity: GuestIdentity) => void	—	Called after guest form submission

Theming and Accessibility

The component uses a shared theme engine that generates WCAG AA-compliant color tokens from your accentColor and darkMode settings. All text meets a minimum 4.5:1 contrast ratio, and accent elements meet 3:1.

For full theming customization, keyboard navigation patterns, ARIA roles, and focus management details, see the @syncagent/react documentation.

Guest Identification

The GuestIdentificationForm component and all guest identification utilities are re-exported from @syncagent/nextjs — no need to install @syncagent/react or @syncagent/js separately.

Available exports:

Export	Kind	Description
GuestIdentificationForm	Component	Pre-built form for collecting guest name, email, and optional phone
GuestIdentificationFormProps	Type	Props interface for the form component
GuestIdentity	Type	Object containing name, email, phone, and generated guestId
GuestFormConfig	Type	Configuration for customizing form text and placeholders
FieldValidationResult	Type	Validation result for individual form fields
validateGuestForm	Function	Validates all guest form fields at once
validateName	Function	Validates a name string (non-empty, non-whitespace)
validateEmail	Function	Validates an email string
generateGuestIdentifier	Function	Generates a deterministic guest_-prefixed ID from an email
GuestIdentificationRequiredError	Class	Error thrown when sending a message before identification

Usage in Next.js App Router

Important: The GuestIdentificationForm is a client component. You must add the "use client" directive at the top of any file that uses it in the Next.js App Router.

// app/support/guest-chat.tsx
"use client";

import {
  useCustomerChat,
  GuestIdentificationForm,
  SyncAgentClient,
} from "@syncagent/nextjs";
import type { SyncAgentConfig, GuestIdentity } from "@syncagent/nextjs";

export function GuestChat({ config }: { config: SyncAgentConfig }) {
  const client = new SyncAgentClient(config);

  const {
    messages,
    sendMessage,
    isLoading,
    isIdentified,
    guestIdentity,
    identifyGuest,
  } = useCustomerChat({
    client,
    onGuestIdentified: (identity: GuestIdentity) => {
      console.log("Guest identified:", identity.guestId);
    },
  });

  if (!isIdentified) {
    return (
      <GuestIdentificationForm
        onSubmit={(identity) => identifyGuest(identity)}
        config={{
          title: "Welcome to Support",
          subtitle: "Please introduce yourself to get started",
          submitButtonText: "Start Chat",
        }}
      />
    );
  }

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i}>{msg.role}: {msg.content}</div>
      ))}
      <input
        onKeyDown={(e) => {
          if (e.key === "Enter") sendMessage(e.currentTarget.value);
        }}
        disabled={isLoading}
      />
    </div>
  );
}

// app/support/page.tsx — Server Component (no "use client")
import { createCustomerServerConfig } from "@syncagent/nextjs/server";
import { GuestChat } from "./guest-chat";

export default async function SupportPage() {
  const config = createCustomerServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    externalUserId: undefined, // omit to enable guest flow
  });

  return <GuestChat config={config} />;
}

When externalUserId is not provided, the useCustomerChat hook requires guest identification before messages can be sent. The GuestIdentificationForm collects the guest's details and the identity is persisted to localStorage so returning visitors are recognized automatically.

Dual Mode (Database + Customer Agent)

⚠️ Deprecated: createDual() will be removed in a future major version. Use createDualServerConfig() instead — it keeps your connection string on the server and returns separate db and support configs for Client Components.

Before (deprecated):

import { SyncAgentClient } from "@syncagent/js";

const { db, support } = SyncAgentClient.createDual({
  apiKey: process.env.SYNCAGENT_KEY!,
  connectionString: process.env.DATABASE_URL!,
  externalUserId: session.user.id,
});

After (recommended):

import { createDualServerConfig } from "@syncagent/nextjs/server";

const { db, support } = createDualServerConfig({
  apiKey: process.env.SYNCAGENT_KEY!,
  connectionString: process.env.DATABASE_URL!,
  externalUserId: session.user.id,
});

Legacy pattern (deprecated):

// app/dashboard/page.tsx — Server Component
import { SyncAgentClient } from "@syncagent/js";
import { getServerSession } from "next-auth";
import { AdminChat } from "./admin-chat";
import { CustomerWidget } from "./customer-widget";

export default async function DashboardPage() {
  const session = await getServerSession();

  const { db, support } = SyncAgentClient.createDual({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    externalUserId: session.user.id,
  });

  // Pass each client to its respective widget
  return (
    <div>
      <AdminChat config={db} />
      <CustomerWidget config={support} />
    </div>
  );
}

Unified Dual Mode

The createDualServerConfig() server helper creates a unified dual-mode configuration from a Server Component. It returns separate db and support config objects that you pass to Client Components — keeping your connection string out of the browser bundle while enabling both database agent and customer agent modes.

Server Component

// app/dashboard/page.tsx — Server Component
import { createDualServerConfig } from "@syncagent/nextjs/server";
import { getServerSession } from "next-auth";
import { AdminChat } from "./admin-chat";
import { CustomerWidget } from "./customer-widget";

export default async function DashboardPage() {
  const session = await getServerSession();

  const { db, support } = createDualServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    externalUserId: session.user.id,
    filter: { organizationId: session.user.orgId },
  });

  return (
    <div>
      <AdminChat config={db} />
      <CustomerWidget config={support} />
    </div>
  );
}

DualServerConfig Return Type

interface DualServerConfig {
  db: SyncAgentConfig;
  support: SyncAgentConfig;
}

• db — Configuration for the database agent mode (uses chat())
• support — Configuration for the customer agent mode (uses customerChat())

Validation Rules

createDualServerConfig() validates the provided options and throws an error if required fields are missing:

Condition	Error Message
apiKey is missing	@syncagent/nextjs: apiKey is required
externalUserId is missing	@syncagent/nextjs: externalUserId is required for dual mode
connectionString is missing (and toolsOnly is not true)	@syncagent/nextjs: connectionString is required (or set toolsOnly: true)

When toolsOnly: true is set, connectionString is not required — the agent will only use custom tools without database access.

Re-exported Hook: useDualChat

useDualChat is re-exported from @syncagent/nextjs for client-side use — no need to install @syncagent/react separately:

import { useDualChat } from "@syncagent/nextjs";

Use useDualChat in your Client Components to manage both database and customer chat state from a single hook. See the @syncagent/react documentation for full useDualChat() API reference.

Middleware Hooks (Client-side Only)

Functions like onBeforeToolCall can't be serialized from Server Components. Define them in a Client Component:

// app/components/chat.tsx — "use client"
import { SyncAgentChat } from "@syncagent/nextjs";

export function Chat({ serverConfig }) {
  return (
    <SyncAgentChat
      config={{
        ...serverConfig,
        onBeforeToolCall: (name, args) => {
          console.log(`[Audit] ${name}`, args);
          return true;
        },
      }}
    />
  );
}

Re-exported Components

All components and hooks from @syncagent/react are re-exported:

import { SyncAgentChat, SyncAgentProvider, useSyncAgent, SyncAgentClient } from "@syncagent/nextjs";

API Reference

Function	Returns	Context	Description
createServerConfig(options)	SyncAgentConfig	Server only	Create config with all options
createServerConfigFromEnv(overrides?)	SyncAgentConfig	Server only	Create config from SYNCAGENT_KEY + DATABASE_URL env vars
createCustomerServerConfig(options)	SyncAgentConfig	Server only	Create config for customer agent mode (requires externalUserId)
createDualServerConfig(options)	DualServerConfig	Server only	Create unified dual-mode config requiring externalUserId — returns { db, support }

TypeScript Types

The following types and hooks are re-exported from @syncagent/nextjs for client-side use:

import { useDualChat, DualChatReturn, UseDualChatOptions } from "@syncagent/nextjs";

Export	Kind	Description
useDualChat	Hook	Manages both database and customer chat state from a single hook
DualChatReturn	Type	Return type of useDualChat() — contains db and support namespaces
UseDualChatOptions	Type	Options interface for useDualChat() — accepts context, onData, onEscalated, onResolved

These are re-exported from @syncagent/react so you don't need to install it separately.

Security

• Your database connection string is never stored on SyncAgent servers
• createServerConfig ensures the connection string stays in the server bundle
• API keys are hashed with bcrypt — raw keys are never stored
• Never use NEXT_PUBLIC_ prefix for your database URL

Plans & Pricing

Plan	Requests/mo	Collections	Price
Free (+ 14-day trial)	100 (500 during trial)	5	GH₵0
Starter	5,000	20	GH₵150/mo
Pro	50,000	Unlimited	GH₵500/mo
Enterprise	Unlimited	Unlimited	Custom

View full pricing →

Resources

• Documentation
• Dashboard
• Pricing
• Changelog

License

MIT