DOCSEARCHbyAlgolia
Submit Docs

Vercel Chatbot Template

repository·main·Indexed 12 days ago

https://github.com/vercel/chatbot

An open-source, production-ready template for building AI-powered chat applications using Next.js, the AI SDK, and Vercel's ecosystem. Version 3.1.0 features support for Vercel AI Gateway, Neon Serverless Postgres, Vercel Blob, and Auth.js. It includes a sophisticated artifact system for executing Python code via Pyodide, generating images, managing spreadsheets, and handling text documents with version control and real-time streaming.

Tokens
13K
Snippets
41
Records
53
Agent score
97%

What's inside Vercel Chatbot

  1. Overview of Chatbot features and stack

    main

    Chatbot is an open-source template designed for building chatbot applications using Next.js and the AI SDK.

    Key technologies include:

    • Next.js App Router: Uses React Server Components (RSCs) and Server Actions.
    • AI SDK: Provides a unified API for text generation, structured objects, and tool calls.
    • shadcn/ui: Built with Tailwind CSS and Radix UI primitives.
    • Data Persistence: Uses Neon Serverless Postgres for chat history and Vercel Blob for file storage.
    • Auth.js: Handles authentication.

  2. Configure Model Providers via AI Gateway

    main

    The template uses Vercel AI Gateway to access multiple models through a unified interface. Model configuration and provider routing are managed in lib/ai/models.ts.

    Supported models include:

    • Mistral
    • Moonshot
    • DeepSeek
    • OpenAI
    • xAI

    You can also switch to direct LLM providers (like Anthropic or Cohere) by modifying the AI SDK implementation in the codebase.

  3. Run Chatbot locally

    main

    To run the project on your local machine, follow these steps. Ensure you have the environment variables defined in .env.example configured in a .env file or via Vercel environment variables.

    1. Install the Vercel CLI: npm i -g vercel
    2. Link your local instance to Vercel and GitHub: vercel link
    3. Pull your environment variables: vercel env pull
    4. Install dependencies, migrate the database, and start the development server.
    # Install Vercel CLI globally
npm i -g vercel

# Link and pull env vars
vercel link
vercel env pull

# Install, migrate, and run
pnpm install
pnpm db:migrate
pnpm dev

  5. Configure Artifacts tool usage via artifactsPrompt

    main

    The artifactsPrompt defines the operational logic for the Artifacts side panel (which supports code, text, and sheet kinds). When building or customizing a chatbot that uses these tools, the model follows these critical rules:

    • Tool Chaining: Only call ONE tool per response. After a createDocument, editDocument, or updateDocument call, the model must STOP and not chain further tools.
    • Response Style: After modifying an artifact, the model must NEVER output the artifact's content in the chat. It should only provide a 1-2 sentence confirmation.
    • createDocument: Used for new content (essays, code, etc.). Must specify kind: 'code', kind: 'text', or kind: 'sheet'.
    • editDocument: Preferred for targeted changes using find-and-replace (old_string and new_string). It is recommended to include 3-5 surrounding lines in old_string to ensure uniqueness.
    • updateDocument: Used for full rewrites when editDocument is inefficient.
    • requestSuggestions: Only used when the user explicitly asks for suggestions on an existing document.

  6. Authenticate AI Gateway

    main

    Authentication for the AI Gateway depends on your deployment environment:

    • Vercel deployments: Authentication is handled automatically via OIDC tokens.
    • Non-Vercel deployments: You must set the AI_GATEWAY_API_KEY environment variable in your .env.local file.

  7. Configure the Playwright webServer

    main

    To ensure the application is running before tests start, Playwright is configured to manage a local development server via the webServer option.

    • Command: Runs pnpm dev to start the server.
    • URL: Monitors ${baseURL}/ping to determine when the server is ready.
    • Timeout: Waits up to 120,000ms for the server to become available.
    • Reuse: If not running in a CI environment, it will attempt to reuse an existing server to speed up execution.
    webServer: {
  command: "pnpm dev",
  reuseExistingServer: !process.env.CI,
  timeout: 120 * 1000,
  url: `${baseURL}/ping`,
}

  8. Configure NextAuth authentication settings

    main

    The authConfig object defines the core authentication behavior for the application using NextAuthConfig. It specifies the API base path, custom authentication pages, and security settings like trustHost.

    Key configuration properties:

    • basePath: The endpoint prefix for authentication requests (defaults to /api/auth).
    • pages: Defines custom routes for authentication flows:
      • newUser: The path where new users are redirected.
      • signIn: The path for the sign-in page.
    • providers: An array of authentication providers (e.g., Google, GitHub) to be used.
    • trustHost: A boolean flag that, when set to true, allows the application to trust the host header, which is often necessary in certain deployment environments.
    export const authConfig = {
  basePath: "/api/auth",
  callbacks: {},
  pages: {
    newUser: `${base}/`,
    signIn: `${base}/login`,
  },
  providers: [],
  trustHost: true,
} satisfies NextAuthConfig;

  9. Configure Playwright timeouts and retries

    main

    The testing configuration defines specific limits for test execution and error handling:

    • Test Timeout: Each individual test has a global timeout of 240,000ms (4 minutes).
    • Expect Timeout: Assertions (expect) have a timeout of 240,000ms.
    • WebServer Timeout: The server startup process has a timeout of 120,000ms.
    • Retries: Currently set to 0. Note that in CI environments, you may want to adjust this behavior.
    • Workers: The number of workers is limited to 2 to prevent browser crashes, regardless of whether running in CI or locally.
    export default defineConfig({
  timeout: 240 * 1000,
  expect: {
    timeout: 240 * 1000,
  },
  retries: 0,
  workers: process.env.CI ? 2 : 2,
});

  10. Configure Playwright for E2E testing

    main

    The project uses Playwright for end-to-end (E2E) testing. The configuration is managed via playwright.config.ts and is designed to run against a local development server.

    Key configuration behaviors:

    • Environment Variables: Uses .env.local via dotenv to load environment variables.
    • Base URL: Automatically constructs the baseURL using the PORT environment variable (defaulting to 3000).
    • Test Directory: Tests are located in the ./tests directory.
    • E2E Project: A specific project named e2e is configured to match files in the e2e/ directory using the Desktop Chrome device profile.
    • Parallelism: Tests run in fullyParallel mode.
    • CI Behavior: On Continuous Integration (CI), forbidOnly is enabled to prevent accidental test.only usage, and reuseExistingServer is disabled.
    import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  fullyParallel: true,
  projects: [
    {
      name: "e2e",
      testMatch: /e2e\/.*\.test\.ts/,
      use: { ...devices["Desktop Chrome"] },
    },
  ],
  use: {
    baseURL: `http://localhost:${PORT}`,
    trace: "retain-on-failure",
  },
});

  11. Configure Drizzle ORM for the chatbot project

    main

    The project uses drizzle-kit for database migrations and schema management. The configuration is defined in drizzle.config.ts and requires a PostgreSQL database. It uses .env.local to load environment variables, specifically looking for POSTGRES_URL to provide database credentials.

    import { config } from "dotenv";
import { defineConfig } from "drizzle-kit";

config({
  path: ".env.local",
});

export default defineConfig({
  dbCredentials: {
    url: process.env.POSTGRES_URL ?? "",
  },
  dialect: "postgresql",
  out: "./lib/db/migrations",
  schema: "./lib/db/schema.ts",
});

  12. Troubleshoot database errors

    main

    Most database query functions in this module wrap underlying errors in a ChatbotError. If you encounter database issues, check for the following error codes:

    • bad_request:database: Occurs during failed inserts, updates, or deletes (e.g., constraint violations).
    • not_found:database: Occurs when a requested resource (like a chat or document) does not exist in the database.