Chat SDK

Chat SDK is a free, open-source template built with Next.js and the AI SDK that helps you quickly build powerful chatbot applications.

Read Docs · Features · Model Providers · Deployment · Running locally

Features

• Next.js App Router
  • Advanced routing for seamless navigation and performance
  • React Server Components (RSCs) and Server Actions for server-side rendering and increased performance
• AI SDK
  • Unified API for generating text, structured objects, and tool calls with LLMs
  • Hooks for building dynamic chat and generative user interfaces
  • Uses a custom backend for AI model integration
• shadcn/ui
  • Styling with Tailwind CSS
  • Component primitives from Radix UI for accessibility and flexibility
• Data Persistence
  • Managed by the custom backend API
  • Chat history and user data are stored server-side
• Auth.js
  • Simple and secure authentication

Model Providers

This application has been configured to use a custom backend for AI model integration. It requires the following environment variables:

• API_BASE_URL: The base URL for your custom API (e.g., https://api.yourdomain.com)
• API_SECRET: Your authentication secret key for the custom API

The backend API should support:

1. Chat completion streams using the optimized SSE format
2. Title generation for new conversations
3. Proper authentication via Bearer token

The chat API will receive:

• User messages and conversation history
• System prompts and context information
• User type and permissions data

Deployment

AWS Amplify Deployment

When deploying to AWS Amplify, add all environment variables in the Amplify console under "Environment variables":

• AUTH_SECRET: Generate a random secret for authentication (use https://generate-secret.vercel.app/32)
• API_BASE_URL: Your custom backend API base URL (e.g., https://api.yourdomain.com)
• API_SECRET: Authentication secret key for your custom API
• REDIS_URL: Redis connection URL (if using Redis)
• GOOGLE_CLIENT_ID: Your Google OAuth client ID
• GOOGLE_CLIENT_SECRET: Your Google OAuth client secret

The build process will automatically create a .env.production file with these variables and set AUTH_TRUST_HOST=true for AWS Amplify's reverse proxy.

⚠️ Security Note: This approach stores secrets as environment variables that are accessible during build time and written to .env.production. While this simplifies deployment, it's not a security best practice. For production applications with sensitive data, consider using AWS Parameter Store or Secrets Manager for runtime secret injection instead. This tradeoff was made for deployment simplicity.

Running locally

You will need to use the environment variables defined in .env.example to run Next.js AI Chatbot. It's recommended you use Vercel Environment Variables for this, but a .env file is all that is necessary.

Note: You should not commit your .env file or it will expose secrets that will allow others to control access to your various AI and authentication provider accounts.

make install
make dev

Your app template should now be running on localhost:3000.

Code Quality

# Run all code quality checks (lint:fix, format, and type-check)
make check

Note: This project uses Husky to automatically run make check as a pre-commit hook. All commits will be validated for code quality before being allowed.

Testing

This application uses Playwright for end-to-end testing. Important: Since the frontend now integrates with a custom backend API, you must have the backend running before running tests.

Prerequisites

1. Backend Setup: Ensure your custom backend is running with these commands:

   # In your backend directory:
   make dev

2. Frontend Test Setup (one-time):

   make setup-tests

Running Tests

# Run all tests
make test-all

# Run tests with UI
make test-ui

# Run specific tests
PLAYWRIGHT=True NEXT_PUBLIC_PLAYWRIGHT=True pnpm exec playwright test tests/e2e/chat.test.ts

# Run tests by name pattern
PLAYWRIGHT=True NEXT_PUBLIC_PLAYWRIGHT=True pnpm exec playwright test -g "test name pattern"

Troubleshooting Tests

• If the "Ada can resume chat generation..." tests fail intermittently, you may need to increase the SECOND_REQUEST_DELAY constant in /tests/routes/chat.test.ts. This delay ensures the second request arrives while the first request is actively streaming.

Backend Integration

This project now uses a custom backend API for all AI model interactions. Key aspects of the implementation:

1. Server-Side Integration: All API calls happen server-side, keeping credentials secure
2. Streaming Protocol: Uses the AI SDK Data Stream Protocol format
3. Centralized Module: Backend API logic is centralized in /lib/api/backend.ts