Chat + Auth Template for Next.js / ChatBotKit / JS

A production-ready chat application template with authentication, conversation persistence, and full ChatBotKit platform integration - built with Next.js, ChatBotKit SDK, next-auth, and shadcn/ui.

Note: This template is deliberately bare-bones. It provides the minimal structure and wiring needed to get a working app, intentionally leaving styling, layout, and architectural choices open so you can build on top without fighting existing opinions.

Why ChatBotKit?

Building an AI chat application typically means sourcing models, a conversation layer, background processing, storage, a tested abilities catalogue, authentication, security, monitoring, and more from separate systems. The cost adds up fast - not just in money, but in engineering time.

ChatBotKit brings all of this into one platform. This template gets you started with a chat app where your agents, skills, datasets, third-party integrations, guardrails, and conversation history are all managed through a single API - no need to stitch together disparate services.

Features

• Authentication - Google OAuth via next-auth with JWT sessions
• Protected Routes - Middleware-based route protection for /chat
• Streaming Chat - Real-time AI responses using ChatBotKit streaming with onStart/onFinish lifecycle hooks
• Platform Agents - Select from your ChatBotKit bots via a dropdown (with optional filtering via CHATBOTKIT_BOT_IDS)
• Conversation Persistence - Conversations are saved to the platform and associated with contacts, so users can resume past conversations
• Conversation History - Slide-out sidebar showing previous conversations with auto-generated labels
• Contact Tracking - Authenticated users are automatically mapped to ChatBotKit contacts by email
• Modern UI - Built with shadcn/ui components and Tailwind CSS
• Server Actions - Next.js server actions for secure API communication (API keys never reach the client)

Technology Stack

• Next.js 14 - App Router with server actions
• ChatBotKit SDK - @chatbotkit/react for client-side streaming, @chatbotkit/sdk for server-side API
• next-auth - Authentication with Google OAuth provider (extensible to GitHub, email, etc.)
• shadcn/ui - Accessible UI components built on Radix primitives
• Tailwind CSS - Utility-first styling with dark mode support

Setup

Prerequisites

• Node.js 18+
• A ChatBotKit account with at least one bot configured
• Google OAuth credentials (for authentication)

Automated Setup

npx create-cbk-app

Follow the prompts and configure environment variables (see below).

Manual Setup

# Clone the repository
git clone <repo-url>
cd template-nextjs-chat-auth-js

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your values (see Environment Variables below)

# Start the development server
npm run dev

Open http://localhost:3000 to get started.

Environment Variables

Variable	Required	Description
CHATBOTKIT_API_SECRET	Yes	ChatBotKit API token from chatbotkit.com/tokens
CHATBOTKIT_BOT_IDS	No	Comma-separated bot IDs to show (e.g., bot_abc,bot_def). Omit to show all bots.
NEXTAUTH_SECRET	Yes	Random secret for JWT signing - generate with openssl rand -base64 32
NEXTAUTH_URL	Yes	Your app URL (e.g., http://localhost:3000)
GOOGLE_CLIENT_ID	Yes	Google OAuth client ID
GOOGLE_CLIENT_SECRET	Yes	Google OAuth client secret

Note: The AI model, backstory, skills, datasets, and all other agent configuration is managed per-bot on the ChatBotKit platform. Your app simply references the bot by ID - all capabilities come from the platform.

Setting Up ChatBotKit

1. Sign up or log in at chatbotkit.com
2. Go to chatbotkit.com/tokens and create an API token
3. Create at least one bot and configure it with:
   • A backstory describing the agent's personality and purpose
   • A model (e.g., GPT-5.4 Mini, Claude Sonnet 4.6)
   • Optional: a skillset with abilities and datasets for RAG
4. Copy the API token to CHATBOTKIT_API_SECRET in your .env file
5. The bot will appear in the agent dropdown. Optionally set CHATBOTKIT_BOT_IDS to restrict which bots are shown.

Getting Google OAuth Credentials

1. Go to Google Cloud Console
2. Create a new OAuth 2.0 Client ID
3. Set authorized redirect URI to http://localhost:3000/api/auth/callback/google
4. Copy the Client ID and Client Secret to your .env file

How It Works

Architecture

Browser (React)          Server Actions           ChatBotKit Platform
┌──────────────┐        ┌──────────────┐         ┌──────────────────┐
│ ConversationManager │──→│ complete()   │──→│ streamComplete()   │
│ (streaming client)  │←──│ onStart()    │   │ Bot config + skills│
│                     │   │ onFinish()   │   │ Datasets + RAG     │
│ Bot Selector        │──→│ listBots()   │──→│ Contacts           │
│ Conversation Sidebar│──→│ listConvos() │──→│ Conversations      │
└──────────────┘        └──────────────┘         └──────────────────┘

1. Authentication - User signs in via Google OAuth. The session is JWT-based (24h expiry).
2. Contact Resolution - On first chat load, the user's email is used to ensure a contact exists on the ChatBotKit platform via cbk.contact.ensure().
3. Bot Selection - Available bots are fetched from the platform. The user selects one from the dropdown.
4. Streaming - Messages are sent via server actions. The streamComplete function streams the response token-by-token back to the browser.
5. Persistence - onStart creates a conversation on the platform; onFinish saves all messages and generates a label. The conversation is linked to the contact.
6. History - The sidebar fetches past conversations for the current contact and allows resuming them.

Stateless Streaming with Server-Side Persistence

The chat uses a stateless streaming pattern - the full message history is sent with every request (no server-side session). Persistence is handled via lifecycle callbacks:

• onStart - Creates a new conversation on the platform (or reuses an existing one) and links it to the contact and bot.
• onFinish - Saves all messages to the conversation and generates a human-readable label from the first exchange.

This gives you the simplicity of stateless streaming with the durability of platform-managed conversations.

Project Structure

├── actions/
│   └── conversation.jsx      # Server actions: complete, listBots, listConversations, etc.
├── app/
│   ├── layout.jsx            # Root layout with providers
│   ├── page.jsx              # Landing page (redirects to /chat or /auth)
│   ├── auth/signin/page.jsx  # Custom sign-in page
│   ├── chat/
│   │   ├── page.jsx          # Chat page (server component, session gate)
│   │   └── chat-page.jsx     # Chat page (client component, all state)
│   └── api/auth/[...nextauth]/
│       └── route.ts          # NextAuth API route
├── components/
│   ├── providers.jsx         # Session provider wrapper
│   ├── chat/
│   │   ├── bot-selector.jsx          # Agent/bot dropdown selector
│   │   ├── chat-area.jsx             # Chat container with ConversationManager
│   │   ├── chat-header.jsx           # Header with sidebar toggle and user menu
│   │   ├── chat-input.jsx            # Auto-resizing textarea with Enter-to-send
│   │   ├── chat-messages.jsx         # Message bubbles with copy-to-clipboard
│   │   └── conversation-sidebar.jsx  # Slide-out conversation history panel
│   └── ui/                   # shadcn/ui primitives (avatar, button, card, etc.)
├── hooks/
│   └── useAutoRevert.js      # Auto-reverting state hook
├── lib/
│   ├── auth-options.js       # NextAuth configuration
│   └── utils.js              # cn() utility for Tailwind class merging
└── middleware.ts              # JWT-based route protection

Customization

Platform Agents

The template fetches your bots directly from the ChatBotKit platform. To configure agents:

1. Go to chatbotkit.com and create bots
2. Configure each bot's backstory, model, skills, datasets, and integrations
3. The bots will automatically appear in the agent dropdown
4. Optionally set CHATBOTKIT_BOT_IDS in .env to restrict which bots are shown

When a bot is selected, its full platform configuration is used - including all skills, datasets, connected services, and guardrails. You can update any of these on the platform and the changes take effect immediately, without redeploying your app.

Filter Available Bots

To only show specific bots in the dropdown, set CHATBOTKIT_BOT_IDS:

CHATBOTKIT_BOT_IDS=bot_abc123,bot_def456

Add AI Functions (Client-Side)

You can also add client-side functions to the functions array in actions/conversation.jsx. These run alongside the platform-configured skills:

{
  name: 'lookupOrder',
  description: 'Look up an order by ID',
  parameters: {
    type: 'object',
    properties: {
      orderId: { type: 'string', description: 'The order ID' },
    },
    required: ['orderId'],
  },
  handler: async ({ orderId }) => {
    const order = await fetchOrder(orderId)
    return { result: order }
  },
},

Tip: For most use cases, prefer adding skills on the ChatBotKit platform instead of hardcoding functions. Platform skills can be added, removed, and reconfigured without code changes.

Add More Auth Providers

Edit lib/auth-options.js to add GitHub, email, or other providers:

import GitHubProvider from 'next-auth/providers/github'

providers: [
  GoogleProvider({ ... }),
  GitHubProvider({
    clientId: process.env.GITHUB_CLIENT_ID,
    clientSecret: process.env.GITHUB_CLIENT_SECRET,
  }),
],

Learn More

• ChatBotKit Documentation
• ChatBotKit SDK Reference
• Next.js Documentation
• next-auth Documentation
• shadcn/ui Documentation