@syncagent/nextjs

@syncagent/nextjs

Next.js SDK for SyncAgent — server-safe helpers and components.

Install

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

Why use this instead of @syncagent/react directly?

The @syncagent/nextjs package provides server-side helpers that let you safely pass your database connection string from Server Components — it never reaches the browser bundle.

Quick Start

// app/dashboard/page.tsx — Server Component
import { createServerConfig } from "@syncagent/nextjs/server";
import { SyncAgentChat } from "@syncagent/nextjs";

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

  const config = createServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    // Multi-tenancy — scope to current user's org
    filter: { organizationId: session.user.orgId },
    // Role-based access
    operations: session.user.isAdmin
      ? ["read", "create", "update", "delete"]
      : ["read"],
  });

  return (
    <SyncAgentChat
      config={config}
      persistKey={session.user.id}
      accentColor="#6366f1"
    />
  );
}

From environment variables

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

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

Environment variables

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

# Optional — for development
NEXT_PUBLIC_SYNCAGENT_BASE_URL=http://localhost:3100

API Reference

createServerConfig(options) — server only

Option	Type	Required	Description
apiKey	string	✅	Your SyncAgent API key
connectionString	string	✅	Your database URL — stays on the server
filter	Record<string,any>	—	Mandatory query filter for multi-tenancy
operations	string[]	—	Restrict operations for this session
baseUrl	string	—	Override API URL (dev only)

createServerConfigFromEnv(overrides?) — server only

Reads SYNCAGENT_KEY and DATABASE_URL from environment variables automatically.

Client components

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

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

Complete example — multi-tenant SaaS

// app/app/[orgSlug]/page.tsx
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);

  // Verify user belongs to this org
  if (!session?.user?.orgId || session.user.orgId !== org.id) {
    redirect("/login");
  }

  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"],
  });

  return (
    <div>
      <h1>Welcome to {org.name}</h1>
      <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,
        }}
      />
    </div>
  );
}

License

MIT