Skip to main content
Cossistant Logo
Widget v0.3.0NEW: Smaller bundles, lazy loading
arrow-leftPreviousarrow-rightNext

Next.js

Install and launch the Cossistant support widget in Next.js.

If you are contributing to the Cossistant repo itself, start with the Contributor Setup Guide so you boot the full monorepo and local services, not just the widget in an existing app.

Quick start with shadcn registry

bunx --bun shadcn@latest add cossistantcom/cossistant/support

The registry installs a Next.js-ready <Support /> starter, the CossistantProvider, the required dependencies, the widget CSS import, and a NEXT_PUBLIC_COSSISTANT_API_KEY placeholder.

1. Add your public API key

Create or copy a browser-safe public key in Settings → Developers and add your development and production hostnames. See API Keys for the exact rules.

.env.local
NEXT_PUBLIC_COSSISTANT_API_KEY=pk_test_xxxx

2. Mount CossistantProvider

tsapp/layout.tsx
import { CossistantProvider } from "@/components/cossistant/provider";
 
import "./globals.css";
 
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <CossistantProvider>{children}</CossistantProvider>
      </body>
    </html>
  );
}

3. Render <Support />

tsapp/page.tsx
import { Support } from "@/components/cossistant/support";
 
export default function Page() {
  return (
    <main>
      <h1>You are ready to chat</h1>
      <Support />
    </main>
  );
}

Quick start with AI prompt

Paste your public key to prefill the prompt, then copy it and run it in ChatGPT, Claude, or Cursor.

cossistant-prompt.md

Manual package install

1. Install the package

pnpm add @cossistant/next

2. Add your public API key

.env.local
NEXT_PUBLIC_COSSISTANT_API_KEY=pk_test_xxxx

3. Add SupportProvider

tsapp/layout.tsx
import { SupportProvider } from "@cossistant/next/provider";
 
import "./globals.css";
 
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <SupportProvider>{children}</SupportProvider>
      </body>
    </html>
  );
}

4. Import styles

The widget does not inject styles automatically. Use support.css when your app already runs Tailwind CSS v4. Use styles.css everywhere else. Both entrypoints share the same widget theme behavior. If your app already exposes standard shadcn-style tokens, the widget will usually pick up colors, radius, fonts, and dark mode automatically. No extra theme mapping is needed to start.

cssapp/globals.css
@import "tailwindcss";
 
@import "@cossistant/next/support.css";

5. Render the widget

tsapp/page.tsx
import { LazySupport } from "@cossistant/next/lazy-support";
import { Suspense } from "react";
 
export default function Page() {
  return (
    <main>
      <h1>You are ready to chat</h1>
      <Suspense fallback={null}>
        <LazySupport />
      </Suspense>
    </main>
  );
}

LazySupport keeps the complete widget UI out of the initial route chunk. If you control when support appears, call preloadSupport from the same entry on hover or focus before rendering it.

6. Identify logged-in visitors (optional)

tsapp/(app)/layout.tsx
import { IdentifySupportVisitor } from "@cossistant/next/identify-visitor";
 
export default function AppLayout({ children }: { children: React.ReactNode }) {
  const user = {
    id: "user_123",
    email: "jane@acme.com",
    name: "Jane Doe",
  };
 
  return (
    <>
      <IdentifySupportVisitor
        externalId={user.id}
        email={user.email}
        name={user.name}
      />
      {children}
    </>
  );
}

7. Display custom messages with SupportConfig defaultMessages (optional)

tsapp/page.tsx
import { LazySupport } from "@cossistant/next/lazy-support";
import { SupportConfig } from "@cossistant/next/support-config";
import { type DefaultMessage, SenderType } from "@cossistant/types";
import { Suspense } from "react";
 
const user: { name: string | null } = {
  name: "Jane Doe",
};
 
const defaultMessages: DefaultMessage[] = [
  {
    content: `Hi ${user.name ?? "there"}, anything I can help with?`,
    senderType: SenderType.TEAM_MEMBER,
  },
];
 
const quickOptions: string[] = ["How to identify a visitor?"];
 
export default function Page() {
  return (
    <>
      <SupportConfig
        defaultMessages={defaultMessages}
        quickOptions={quickOptions}
      />
      <Suspense fallback={null}>
        <LazySupport />
      </Suspense>
    </>
  );
}

Verify the installation

Reload the app and confirm that the support trigger appears, opens the home or conversation screen, and produces no 401/403 API responses. If the trigger is unstyled, import exactly one CSS entrypoint. A 401 usually means the public key is missing or invalid; a 403 usually means the current hostname is absent from the key's allowed domains. See API Keys.

Next in the Support docs

  1. Overview for the fastest path from first render to production-ready widget.
  2. Change One Thing to swap the bubble or first screen without rebuilding the widget.
  3. Match Your Brand to set colors, radius, and dark mode.

Was this page helpful?

Open a prefilled documentation issue so the team can act on your feedback.

Yes, it helpedNeeds improvement
arrow-left What is Cossistant?React arrow-right