Framework guide

Add Chat to Next.js

Use Bootstrapware Chat when your Next.js SaaS needs in-product 1:1 and small-group messaging. The widget is a Client Component. Pass the signed-in user from your session. There are no public chat URLs.

This guide covers App Router. The same package works in Pages Router if you keep the component on the client and avoid putting secret keys in public env vars.

Install

pnpm add @bootstrapware/chat

Import package CSS once for the tree that renders chat. Forgetting the stylesheet is the most common "it looks broken" bug.

Local adapter in a Client Component

Start local for placement and IA. No paid entitlement required. Put the widget in a file with "use client".

"use client";

import { Chat, createLocalAdapter } from "@bootstrapware/chat";
import "@bootstrapware/chat/styles.css";

export function ChatPanel({
  user,
}: {
  user: { id: string; name?: string } | null;
}) {
  if (!user) return <p>Sign in to message.</p>;
  return (
    <Chat
      user={user}
      adapter={createLocalAdapter({ storageKey: "app-chat" })}
    />
  );
}

Render <ChatPanel /> from any Server or Client page. Only the chat island needs to be a Client Component. Adapter resolution: explicit adapter → Hosted when appId + publishable key → otherwise local.

Hosted embed

For Hosted storage, omit adapter and pass app id plus a publishable key. Use NEXT_PUBLIC_ only for publishable values.

<Chat
  appId={process.env.NEXT_PUBLIC_CHAT_APP_ID!}
  publishableKey={process.env.NEXT_PUBLIC_BSW_CHAT_PUBLISHABLE_KEY!}
  user={user}
/>

Never put bsw_live_sec_ or bsw_test_sec_ in NEXT_PUBLIC_. Secret keys stay in Route Handlers or server-only modules. See API keys and environments.

BYO Route Handlers

Implement /api/chat endpoints that enforce your session, then pass adapter methods that fetch those routes. Re-bind authorship from the session. Do not trust client-supplied author.id alone. Contract: adapter.

Limits worth knowing

  • Body max 4,000 (plain text)
  • Groups max 20
  • Attachments: jpeg/png/webp/gif/pdf, 10 MB, 4 per message
  • Hosted: about 30 messages/min and 10 uploads/min per author

Pitfalls specific to Next.js

  • Rendering Chat in a Server Component without "use client"
  • Forgetting @bootstrapware/chat/styles.css
  • Putting a secret key in public env
  • Assuming a public chat URL exists after publish
  • Inventing user.id instead of the session id
  • Trusting client author on BYO routes without session checks

Related: Quickstart · React guide · Cursor guide · Identity · Live demo