In this guide, I'll walk you through building production-grade MCP servers that expose your organization's internal data to AI models. We'll go beyond simple examples and cover authentication, multi-tenancy, streaming, and deployment patterns you'll actually need.

Table of Contents

• Prerequisites

• What is MCP and Why Does It Matter for Internal Data?

• Architecture Overview

• Setting Up the Project

• Building the MCP Server

  • Step 1: Server Skeleton

  • Step 2: Connecting to Internal Data

  • Step 3: Defining Tools

  • Tool Design Principles

  • Step 4: Exposing Resources

  • Step 5: Transport and Startup

• Adding Authentication

  • Bearer Token Authentication

  • OAuth 2.0 for MCP

• Scoping Data Access Per User

• Connecting to Internal APIs

• Building a RAG Tool for Internal Documents

• Production Deployment

  • Dockerizing the MCP Server

  • Health Checks and Monitoring

  • Logging and Audit Trail

• Connecting Your MCP Server to AI Clients

  • Claude Desktop

  • Custom Application (using the MCP Client SDK)

• Common Pitfalls

• Wrapping Up

Prerequisites

This is an advanced guide. You should be comfortable with:

• TypeScript / Node.js

• REST APIs and server-side development

• Basic understanding of LLMs and tool calling

• Familiarity with protocols like JSON-RPC

What is MCP, and Why Does It Matter for Internal Data?

MCP is an open protocol (created by Anthropic) that standardizes how AI assistants discover and invoke external tools. Think of it as a USB-C port for AI — one standard interface that lets any AI model connect to any data source.

Before MCP, connecting an AI assistant to your internal database meant:

• Writing custom tool definitions for each LLM provider

• Hardcoding data access logic into your AI application

• Rebuilding everything when you switched models or added new data sources

MCP separates the data layer from the AI layer. Your MCP server exposes tools and resources. Any MCP-compatible client—Claude, ChatGPT, your custom app—can use them without modification.

For internal data, this is significant because:

• Your CRM, ERP, ticketing system, and wiki all become AI-accessible through one protocol

• Access control stays in your MCP server, not scattered across AI application code

• New AI models or clients automatically get access without rewiring integrations

• Tool definitions live close to the data, making them easier to maintain and version

Architecture Overview

Here's what we're building:

The MCP server sits between your AI client and your internal systems. It handles:

• Tool discovery: Tells the AI what operations are available

• Parameter validation: Ensures the AI sends correct inputs

• Data access: Queries your internal systems

• Response formatting: Returns structured data the AI can reason about

• Authentication: Verifies who's making the request

Setting Up the Project

Let's build an MCP server that exposes an internal employee directory and project management system.

mkdir internal-data-mcp && cd internal-data-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod express pg
npm install -D typescript @types/node @types/express @types/pg tsx

These commands scaffold the project. npm install pulls in the runtime dependencies: the official MCP SDK, Zod for schema validation, Express for the HTTP server, and pg for PostgreSQL. The -D flag installs TypeScript and its type definitions as dev-only dependencies — they're needed to compile the code but don't ship to production. tsx lets you run TypeScript directly during development without a separate compile step.

Now, create your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

This TypeScript config targets ES2022, which supports modern JavaScript features like top-level await. "module": "Node16" and "moduleResolution": "Node16" are required when using the MCP SDK's .js import extensions. "strict": true enables all of TypeScript's strictness checks, which helps catch bugs in tool handlers before they reach production. The outDir/rootDir pair tells the compiler to take source files from src/ and emit compiled JavaScript into dist/.

Building the MCP Server

Step 1: Server Skeleton

Create src/server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer(
  { name: "internal-data", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

The McpServer class from the official SDK handles the JSON-RPC protocol, transport negotiation, and lifecycle management. We declare support for both tools (actions the AI can take) and resources (data the AI can read).

Step 2: Connecting to Internal Data

Let's say you have a PostgreSQL database with employee and project data. Create a data access layer:

// src/db.ts
import pg from "pg";

const pool = new pg.Pool({
  connectionString: process.env.INTERNAL_DB_URL,
  max: 10,
  idleTimeoutMillis: 30000,
});

export interface Employee {
  id: string;
  name: string;
  email: string;
  department: string;
  role: string;
  manager_id: string | null;
  start_date: string;
}

export interface Project {
  id: string;
  name: string;
  status: "active" | "completed" | "on_hold";
  lead_id: string;
  department: string;
  deadline: string | null;
}

export async function searchEmployees(
  query: string,
  department?: string
): Promise<Employee[]> {
  const conditions = ["(name ILIKE \(1 OR email ILIKE \)1 OR role ILIKE $1)"];
  const params: string[] = [`%${query}%`];

  if (department) {
    conditions.push(`department = $${params.length + 1}`);
    params.push(department);
  }

  const result = await pool.query<Employee>(
    `SELECT id, name, email, department, role, manager_id, start_date
     FROM employees
     WHERE ${conditions.join(" AND ")}
     ORDER BY name
     LIMIT 25`,
    params
  );

  return result.rows;
}

export async function getProjectsByStatus(
  status: string
): Promise<Project[]> {
  const result = await pool.query<Project>(
    `SELECT id, name, status, lead_id, department, deadline
     FROM projects
     WHERE status = $1
     ORDER BY deadline ASC NULLS LAST`,
    [status]
  );

  return result.rows;
}

export async function getProjectMembers(
  projectId: string
): Promise<Employee[]> {
  const result = await pool.query<Employee>(
    `SELECT e.id, e.name, e.email, e.department, e.role,
            e.manager_id, e.start_date
     FROM employees e
     JOIN project_members pm ON pm.employee_id = e.id
     WHERE pm.project_id = $1
     ORDER BY e.name`,
    [projectId]
  );

  return result.rows;
}

Notice this is plain SQL with parameterized queries. Your MCP server's data access layer should use whatever your team already uses — Prisma, Drizzle, Knex, raw SQL. MCP doesn't dictate your data access patterns.

Step 3: Defining Tools

Now expose this data through MCP tools. This is where the design matters most. Good tool definitions directly impact how well the AI uses your data.

// src/tools.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import {
  searchEmployees,
  getProjectsByStatus,
  getProjectMembers,
} from "./db.js";

export function registerTools(server: McpServer) {
  // Tool 1: Search the employee directory
  server.tool(
    "search_employees",
    `Search the internal employee directory by name, email, or role.
     Returns matching employees with their department and reporting structure.
     Use this when the user asks about people, teams, or org structure.`,
    {
      query: z
        .string()
        .describe("Search term: employee name, email, or role title"),
      department: z
        .string()
        .optional()
        .describe(
          "Filter by department name (e.g., 'Engineering', 'Marketing')"
        ),
    },
    async ({ query, department }) => {
      const employees = await searchEmployees(query, department);

      if (employees.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No employees found matching "\({query}"\){department ? ` in ${department}` : ""}.`,
            },
          ],
        };
      }

      const formatted = employees
        .map(
          (e) =>
            `- **\({e.name}** (\){e.email})\n  Role: \({e.role} | Dept: \){e.department} | Since: ${e.start_date}`
        )
        .join("\n");

      return {
        content: [
          {
            type: "text",
            text: `Found \({employees.length} employee(s):\n\n\){formatted}`,
          },
        ],
      };
    }
  );

  // Tool 2: List projects by status
  server.tool(
    "list_projects",
    `List internal projects filtered by status.
     Returns project name, lead, department, and deadline.
     Use this when the user asks about ongoing work, project status, or deadlines.`,
    {
      status: z
        .enum(["active", "completed", "on_hold"])
        .describe("Project status to filter by"),
    },
    async ({ status }) => {
      const projects = await getProjectsByStatus(status);

      if (projects.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No ${status} projects found.`,
            },
          ],
        };
      }

      const formatted = projects
        .map(
          (p) =>
            `- **\({p.name}** [\){p.status}]\n  Lead: \({p.lead_id} | Dept: \){p.department} | Deadline: ${p.deadline ?? "None"}`
        )
        .join("\n");

      return {
        content: [
          {
            type: "text",
            text: `\({projects.length} \){status} project(s):\n\n${formatted}`,
          },
        ],
      };
    }
  );

  // Tool 3: Get team members for a project
  server.tool(
    "get_project_team",
    `Get all team members assigned to a specific project.
     Returns employee details for each member.
     Use this when the user asks who is working on a project.`,
    {
      project_id: z
        .string()
        .uuid()
        .describe("The UUID of the project to look up"),
    },
    async ({ project_id }) => {
      const members = await getProjectMembers(project_id);

      if (members.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: "No team members found for this project.",
            },
          ],
        };
      }

      const formatted = members
        .map((m) => `- \({m.name} (\){m.role}, ${m.department})`)
        .join("\n");

      return {
        content: [
          {
            type: "text",
            text: `Project team (\({members.length} members):\n\n\){formatted}`,
          },
        ],
      };
    }
  );
}

server.tool() registers each tool with four arguments: the tool name, a plain-English description the AI reads to decide when to call it, a Zod schema defining the parameters, and the async handler that runs when the tool is invoked. The handler receives validated, typed parameters — Zod rejects malformed inputs before your handler ever runs. Each handler returns a content array; the type: "text" block is the most common format and tells the AI client to treat the response as readable text. Returning an empty result (zero matches) is handled explicitly so the AI gets a useful message rather than an empty array it might misinterpret.

Tool Design Principles

Three things make the difference between tools an AI uses well and tools it struggles with:

1. Descriptive names and descriptions. The AI decides which tool to call based entirely on the description. Be specific about when to use the tool, not just what it does. Compare:

// Vague — the AI won't know when to pick this
"Search employees"

// Specific — the AI knows exactly when this tool is relevant
"Search the internal employee directory by name, email, or role.
 Use this when the user asks about people, teams, or org structure."

2. Typed parameters with descriptions. Use Zod's .describe() on every parameter. The AI needs to understand what each field expects:

// The AI has to guess what format "query" expects
{ query: z.string() }

// The AI knows exactly what to pass
{ query: z.string().describe("Search term: employee name, email, or role title") }

3. Structured return values. Return data in a format the AI can reason about. Use markdown tables or structured lists rather than raw JSON dumps. The AI processes structured text better than deeply nested objects.

Step 4: Exposing Resources

Resources are read-only data the AI can pull into its context. Unlike tools (which the AI invokes during reasoning), resources are typically loaded upfront to provide background knowledge.

// src/resources.ts
import {
  McpServer,
  ResourceTemplate,
} from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerResources(server: McpServer) {
  // Static resource: org chart overview
  server.resource(
    "org-structure",
    "internal://org-structure",
    {
      description:
        "Overview of the organization structure including departments and leadership",
      mimeType: "text/markdown",
    },
    async (uri) => ({
      contents: [
        {
          uri: uri.href,
          mimeType: "text/markdown",
          text: await generateOrgOverview(),
        },
      ],
    })
  );

  // Dynamic resource template: department details
  server.resource(
    "department-info",
    new ResourceTemplate("internal://departments/{name}", {
      list: undefined,
    }),
    {
      description: "Detailed information about a specific department",
      mimeType: "text/markdown",
    },
    async (uri, variables) => ({
      contents: [
        {
          uri: uri.href,
          mimeType: "text/markdown",
          text: await getDepartmentDetails(
            variables.name as string
          ),
        },
      ],
    })
  );
}

server.resource() registers two kinds of resources here. The first uses a fixed URI (internal://org-structure) — this is a static resource the AI can request by name. The second uses a ResourceTemplate, which defines a URI pattern with a {name} placeholder; the AI can request internal://departments/Engineering and the variables.name parameter will be populated with "Engineering" at runtime. Both resources return a contents array with mimeType: "text/markdown" — this tells the client how to render the response. Resources differ from tools in that they're meant to be read as background context, not invoked as actions.

Resources are useful for data that provides context rather than answering a specific question — company policies, API documentation, database schemas, configuration references.

Step 5: Transport and Startup

MCP supports multiple transports. For internal data servers, you'll typically use one of two:

Streamable HTTP — the recommended transport for remote servers (replaces the older SSE transport):

// src/index.ts
import express from "express";
import { randomUUID } from "node:crypto";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { registerTools } from "./tools.js";
import { registerResources } from "./resources.js";

const app = express();
app.use(express.json());

const server = new McpServer(
  { name: "internal-data", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

registerTools(server);
registerResources(server);

// Store transports by session ID
const transports = new Map<string, StreamableHTTPServerTransport>();

// Handle all MCP requests on a single endpoint
app.all("/mcp", async (req, res) => {
  // Check for existing session
  const sessionId = req.headers["mcp-session-id"] as string | undefined;

  if (sessionId && transports.has(sessionId)) {
    // Existing session — route to its transport
    const transport = transports.get(sessionId)!;
    await transport.handleRequest(req, res);
    return;
  }

  if (sessionId && !transports.has(sessionId)) {
    // Unknown session ID
    res.status(404).json({ error: "Session not found" });
    return;
  }

  // New session — create transport and connect
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => randomUUID(),
    onsessioninitialized: (id) => {
      transports.set(id, transport);
    },
  });

  transport.onclose = () => {
    if (transport.sessionId) {
      transports.delete(transport.sessionId);
    }
  };

  await server.connect(transport);
  await transport.handleRequest(req, res);
});

app.listen(3100, () => {
  console.log("MCP server running on http://localhost:3100/mcp");
});

This sets up a single /mcp endpoint that handles all MCP communication. When a new client connects (no mcp-session-id header), a StreamableHTTPServerTransport is created and stored in the transports Map keyed by a generated UUID. On subsequent requests, the session ID from the header is used to look up the existing transport and route the request to it — this is how the server maintains stateful sessions with multiple clients simultaneously. transport.onclose cleans up the Map entry when a session ends, preventing memory leaks. The StdioServerTransport alternative (shown below) skips all of this: it reads from stdin and writes to stdout, which is how Claude Desktop spawns local servers as child processes.

Stdio — for local development or when the MCP client spawns the server as a child process:

// src/stdio.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { registerTools } from "./tools.js";
import { registerResources } from "./resources.js";

const server = new McpServer(
  { name: "internal-data", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

registerTools(server);
registerResources(server);

const transport = new StdioServerTransport();
await server.connect(transport);

For internal data in a production setting, HTTP/SSE is almost always what you want. Stdio is convenient for development and when the client and server run on the same machine.

Adding Authentication

Internal data servers need authentication. You don't want every AI client on the network querying your employee database unauthenticated.

Bearer Token Authentication

The simplest approach is to validate a token on every request:

// src/auth-middleware.ts
import { Request, Response, NextFunction } from "express";

interface AuthenticatedRequest extends Request {
  userId?: string;
  orgId?: string;
}

export function authMiddleware(
  req: AuthenticatedRequest,
  res: Response,
  next: NextFunction
) {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith("Bearer ")) {
    return res.status(401).json({ error: "Missing authorization header" });
  }

  const token = authHeader.slice(7);

  try {
    // Validate against your internal auth system
    const claims = validateInternalToken(token);
    req.userId = claims.sub;
    req.orgId = claims.org;
    next();
  } catch {
    return res.status(403).json({ error: "Invalid token" });
  }
}

function validateInternalToken(token: string) {
  // Replace with your actual token validation:
  // - JWT verification against your auth service
  // - API key lookup in your database
  // - Session token validation against Redis
  // This is a placeholder
  return { sub: "user-123", org: "org-456" };
}

The middleware checks every request for an Authorization: Bearer <token> header before it reaches the MCP handler. validateInternalToken is a placeholder — replace it with your real validation logic: JWT verification using a library like jsonwebtoken, an API key lookup in your database, or a session token check against Redis. The validated claims are attached to the request object (req.userId, req.orgId) so downstream tool handlers can use them for access scoping. The app.use("/mcp", authMiddleware) line ensures no request reaches the MCP endpoint without passing this check first.

Add it to your Express app:

app.use("/mcp", authMiddleware);

OAuth 2.0 for MCP

For clients that support MCP's built-in OAuth flow (like Claude Desktop), you can implement the full OAuth handshake. The MCP SDK provides the OAuthServerProvider interface with these required methods:

import type { OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
import type {
  AuthorizationParams,
  OAuthClientInformationFull,
  OAuthRegisteredClientsStore,
  OAuthTokens,
  AuthInfo,
} from "@modelcontextprotocol/sdk/server/auth/types.js";

class InternalOAuthProvider implements OAuthServerProvider {
  // Store for registered OAuth clients
  get clientsStore(): OAuthRegisteredClientsStore {
    return this._clientsStore;
  }

  private _clientsStore: OAuthRegisteredClientsStore = {
    async getClient(clientId: string) {
      // Look up the registered client in your database
      return db.getOAuthClient(clientId);
    },
    async registerClient(clientMetadata) {
      // Register a new dynamic client
      return db.createOAuthClient(clientMetadata);
    },
  };

  // Redirect the user to your internal SSO for authorization
  async authorize(
    client: OAuthClientInformationFull,
    params: AuthorizationParams,
    res: Response
  ): Promise<void> {
    const authUrl = new URL(
      "https://sso.internal.company.com/authorize"
    );
    authUrl.searchParams.set("client_id", client.client_id);
    authUrl.searchParams.set("redirect_uri", params.redirectUri);
    authUrl.searchParams.set("state", params.state ?? "");
    authUrl.searchParams.set(
      "code_challenge",
      params.codeChallenge
    );
    // The method writes to the response directly
    res.redirect(authUrl.toString());
  }

  // Return the PKCE challenge for a given authorization code
  async challengeForAuthorizationCode(
    _client: OAuthClientInformationFull,
    authorizationCode: string
  ): Promise<string> {
    const session = await db.getSessionByCode(authorizationCode);
    return session.codeChallenge;
  }

  // Exchange authorization code for access + refresh tokens
  async exchangeAuthorizationCode(
    client: OAuthClientInformationFull,
    authorizationCode: string,
    _codeVerifier?: string,
    _redirectUri?: string
  ): Promise<OAuthTokens> {
    const response = await fetch(
      "https://sso.internal.company.com/token",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({
          grant_type: "authorization_code",
          code: authorizationCode,
          client_id: client.client_id,
        }),
      }
    );

    return response.json() as Promise<OAuthTokens>;
  }

  // Refresh expired tokens
  async exchangeRefreshToken(
    client: OAuthClientInformationFull,
    refreshToken: string
  ): Promise<OAuthTokens> {
    const response = await fetch(
      "https://sso.internal.company.com/token",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({
          grant_type: "refresh_token",
          refresh_token: refreshToken,
          client_id: client.client_id,
        }),
      }
    );

    return response.json() as Promise<OAuthTokens>;
  }

  // Validate an access token on every request
  async verifyAccessToken(token: string): Promise<AuthInfo> {
    const response = await fetch(
      "https://sso.internal.company.com/introspect",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({ token }),
      }
    );

    const data = await response.json();
    if (!data.active) throw new Error("Token inactive");

    return {
      token,
      clientId: data.client_id,
      scopes: data.scope?.split(" ") ?? [],
      expiresAt: data.exp,
    };
  }
}

InternalOAuthProvider implements the OAuthServerProvider interface, which the MCP SDK calls at each stage of the OAuth flow. clientsStore handles dynamic client registration — MCP clients like Claude Desktop register themselves the first time they connect. authorize() redirects the user to your internal SSO; it writes directly to the Express response. challengeForAuthorizationCode() returns the PKCE code challenge stored when the authorization session began — this is how the token exchange is verified without transmitting secrets. exchangeAuthorizationCode() and exchangeRefreshToken() make server-to-server calls to your SSO's token endpoint, keeping credentials out of the browser. verifyAccessToken() is called on every incoming MCP request using the token introspection endpoint to confirm the token is still active and extract the user's scopes.

Scoping Data Access Per User

This is the most important part of an internal data MCP server: the AI should only access data the requesting user is authorized to see.

Don't skip this. Without user-scoped access, you're building a data exfiltration tool with an AI wrapper.

// src/scoped-tools.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function registerScopedTools(
  server: McpServer,
  getUserContext: () => { userId: string; orgId: string; role: string }
) {
  server.tool(
    "search_employees",
    "Search the employee directory. Results are filtered based on your access level.",
    {
      query: z.string().describe("Name, email, or role to search for"),
    },
    async ({ query }) => {
      const ctx = getUserContext();

      // Enforce access boundaries
      let departmentFilter: string | undefined;

      if (ctx.role === "manager") {
        // Managers see their department only
        departmentFilter = await getUserDepartment(ctx.userId);
      } else if (ctx.role === "employee") {
        // Regular employees see limited fields
        departmentFilter = await getUserDepartment(ctx.userId);
      }
      // Admins and HR see everything — no filter

      const employees = await searchEmployees(query, departmentFilter);

      // Redact sensitive fields based on role
      const results = employees.map((e) => ({
        name: e.name,
        email: e.email,
        department: e.department,
        role: e.role,
        // Only HR and admins see start date and manager info
        ...(["admin", "hr"].includes(ctx.role)
          ? { start_date: e.start_date, manager_id: e.manager_id }
          : {}),
      }));

      return {
        content: [
          {
            type: "text",
            text: formatEmployeeList(results),
          },
        ],
      };
    }
  );
}

The pattern here:

1. Extract user context from the authenticated session

2. Filter queries at the database level (not after fetching everything)

3. Redact fields the user shouldn't see

4. Log access for audit trails

Connecting to Internal APIs

Not all internal data lives in databases. You often need to wrap existing internal APIs:

server.tool(
  "get_ticket_details",
  `Look up a support ticket from the internal ticketing system.
   Returns ticket status, assignee, priority, and recent updates.`,
  {
    ticket_id: z
      .string()
      .regex(/^TK-\d+$/)
      .describe("Ticket ID in format TK-12345"),
  },
  async ({ ticket_id }) => {
    const ctx = getUserContext();

    const response = await fetch(
      `\({process.env.TICKETING_API_URL}/api/v2/tickets/\){ticket_id}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.TICKETING_SERVICE_TOKEN}`,
          "X-On-Behalf-Of": ctx.userId,
        },
      }
    );

    if (response.status === 404) {
      return {
        content: [
          { type: "text", text: `Ticket ${ticket_id} not found.` },
        ],
      };
    }

    if (response.status === 403) {
      return {
        content: [
          {
            type: "text",
            text: `You don't have access to ticket ${ticket_id}.`,
          },
        ],
      };
    }

    const ticket = await response.json();

    return {
      content: [
        {
          type: "text",
          text: [
            `**\({ticket.id}: \){ticket.title}**`,
            `Status: \({ticket.status} | Priority: \){ticket.priority}`,
            `Assignee: ${ticket.assignee?.name ?? "Unassigned"}`,
            `Created: ${ticket.created_at}`,
            "",
            `**Latest Update:**`,
            ticket.updates?.[0]?.body ?? "No updates yet.",
          ].join("\n"),
        },
      ],
    };
  }
);

Key points when wrapping internal APIs:

• Use service tokens for server-to-server auth, but pass user identity via headers like X-On-Behalf-Of

• Handle HTTP errors explicitly — return user-friendly messages, not raw error objects

• Validate input formats — the regex on ticket_id prevents injection and guides the AI on expected format

• Don't leak internal implementation details in error messages

Building a RAG Tool for Internal Documents

One of the highest-value use cases: letting the AI search your internal knowledge base. Here's a tool that performs vector search against an internal document store:

server.tool(
  "search_internal_docs",
  `Search the internal knowledge base for relevant documents.
   Covers engineering docs, runbooks, architecture decisions, and policies.
   Use this when the user asks about internal processes, systems, or decisions.`,
  {
    query: z
      .string()
      .describe("Natural language search query"),
    category: z
      .enum(["engineering", "policy", "runbook", "architecture", "all"])
      .default("all")
      .describe("Document category to search within"),
    limit: z
      .number()
      .min(1)
      .max(10)
      .default(5)
      .describe("Maximum number of results"),
  },
  async ({ query, category, limit }) => {
    // Generate embedding for the search query
    const embedding = await generateEmbedding(query);

    // Vector similarity search against your document store
    const results = await pool.query(
      `SELECT
         d.id,
         d.title,
         d.category,
         d.content_chunk,
         d.source_url,
         d.updated_at,
         1 - (d.embedding <=> $1::vector) AS similarity
       FROM document_chunks d
       WHERE (\(2 = 'all' OR d.category = \)2)
         AND 1 - (d.embedding <=> $1::vector) > 0.7
       ORDER BY d.embedding <=> $1::vector
       LIMIT $3`,
      [JSON.stringify(embedding), category, limit]
    );

    if (results.rows.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No relevant documents found for "${query}".`,
          },
        ],
      };
    }

    const formatted = results.rows
      .map(
        (doc, i) =>
          `### \({i + 1}. \){doc.title}\n` +
          `Category: \({doc.category} | Updated: \){doc.updated_at} | Relevance: ${(doc.similarity * 100).toFixed(0)}%\n\n` +
          `${doc.content_chunk}\n\n` +
          `Source: ${doc.source_url}`
      )
      .join("\n\n---\n\n");

    return {
      content: [
        {
          type: "text",
          text: `Found \({results.rows.length} relevant document(s):\n\n\){formatted}`,
        },
      ],
    };
  }
);

This tool combines two operations: embedding generation and vector similarity search. generateEmbedding(query) calls an embedding model (such as OpenAI's text-embedding-3-small or a self-hosted model) to convert the user's query into a numeric vector. The SQL query then uses pgvector's <=> operator to compute cosine distance between the query vector and stored document chunk embeddings — lower distance means higher similarity. The 1 - (embedding <=> $1) > 0.7 condition filters out results below 70% similarity, so the AI doesn't receive loosely related noise. Results are ordered by ascending distance (most similar first) and capped by the limit parameter. The formatted output includes a relevance percentage so the AI can communicate confidence levels to the user.

Production Deployment

Dockerizing the MCP Server

FROM node:22-slim AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-slim AS runtime

WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

ENV NODE_ENV=production
EXPOSE 3100

HEALTHCHECK --interval=30s --timeout=5s \
  CMD curl -f http://localhost:3100/health || exit 1

CMD ["node", "dist/index.js"]

The Dockerfile uses a two-stage build. The builder stage installs all dependencies (including devDependencies) and compiles TypeScript to JavaScript in dist/. The runtime stage starts fresh from a clean Node image and copies only the compiled output and node_modules — devDependencies like TypeScript are excluded, keeping the final image small. The HEALTHCHECK instruction tells Docker (and orchestrators like Kubernetes) to poll /health every 30 seconds; if the endpoint fails, the container is marked unhealthy and can be automatically restarted or removed from the load balancer rotation.

Health Checks and Monitoring

Add a health endpoint that verifies your dependencies:

app.get("/health", async (_req, res) => {
  const checks = {
    database: false,
    ticketingApi: false,
  };

  try {
    await pool.query("SELECT 1");
    checks.database = true;
  } catch {}

  try {
    const resp = await fetch(
      `${process.env.TICKETING_API_URL}/health`
    );
    checks.ticketingApi = resp.ok;
  } catch {}

  const healthy = Object.values(checks).every(Boolean);
  res.status(healthy ? 200 : 503).json({
    status: healthy ? "healthy" : "degraded",
    checks,
    uptime: process.uptime(),
  });
});

The /health endpoint runs two dependency checks in parallel: a lightweight SELECT 1 query to confirm the database connection is live, and an HTTP ping to the ticketing API. Both results are collected into a checks object. If any check fails, the endpoint returns HTTP 503 (Service Unavailable) — this is the signal load balancers and container orchestrators use to stop routing traffic to an unhealthy instance. process.uptime() is included as a diagnostic field so you can quickly tell whether a degraded instance just started or has been running for hours.

Logging and Audit Trail

Every tool invocation against internal data should be logged:

function createAuditLogger() {
  return {
    logToolCall(params: {
      userId: string;
      tool: string;
      input: Record<string, unknown>;
      resultSize: number;
      durationMs: number;
    }) {
      // Ship to your logging infrastructure
      // (Datadog, ELK, CloudWatch, etc.)
      console.log(
        JSON.stringify({
          event: "mcp_tool_call",
          timestamp: new Date().toISOString(),
          ...params,
        })
      );
    },
  };
}

createAuditLogger returns a logger object rather than a class instance, which makes it easy to swap the underlying transport (stdout, a logging SDK, etc.) without changing the call sites. The audited wrapper function is a higher-order function: it takes a tool handler and returns a new function with the same signature, but with timing and logging added around the original call. The try/catch ensures a log entry is written even when the handler throws — you want failed calls in your audit trail, not just successful ones. Shipping these logs to a centralized store (Datadog, CloudWatch, ELK) lets you answer questions like "what data did this user's AI session access last Tuesday?" — which is often required for compliance in organizations handling sensitive internal data.

Wrap your tool handlers to automatically log every call:

function audited<T extends Record<string, unknown>>(
  handler: (params: T) => Promise<ToolResult>,
  toolName: string,
  audit: ReturnType<typeof createAuditLogger>
) {
  return async (params: T): Promise<ToolResult> => {
    const start = Date.now();
    const ctx = getUserContext();

    try {
      const result = await handler(params);
      audit.logToolCall({
        userId: ctx.userId,
        tool: toolName,
        input: params,
        resultSize: JSON.stringify(result).length,
        durationMs: Date.now() - start,
      });
      return result;
    } catch (error) {
      audit.logToolCall({
        userId: ctx.userId,
        tool: toolName,
        input: params,
        resultSize: 0,
        durationMs: Date.now() - start,
      });
      throw error;
    }
  };
}

Connecting Your MCP Server to AI Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "internal-data": {
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer your-internal-token"
      }
    }
  }
}

Custom Application (using the MCP Client SDK)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3100/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${userToken}`,
      },
    },
  }
);

const client = new Client(
  { name: "my-ai-app", version: "1.0.0" }
);

await client.connect(transport);

// Discover available tools
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));

// Call a tool
const result = await client.callTool({
  name: "search_employees",
  arguments: { query: "engineering manager" },
});

console.log(result.content);

StreamableHTTPClientTransport manages the HTTP connection to your MCP server, including attaching the Authorization header to every request. client.connect(transport) performs the MCP initialization handshake — the client announces its capabilities and the server responds with the list of available tools and resources. client.listTools() returns the full tool catalog, which you can use to dynamically build a UI or pass directly to an LLM's tool-calling API. client.callTool() sends a JSON-RPC request to invoke a specific tool by name and returns the content array from the handler — the same format the AI model receives. In a production application, you'd pass this content back to the model as a tool result in the conversation history.

Common Pitfalls

1. Returning too much data. LLMs have context limits. If your database query returns 500 rows, don't send them all. Paginate, summarize, or limit results. 25 items is a reasonable default.

2. Tool descriptions that are too generic. If you have search_employees and search_contractors, the AI needs to know the difference. Don't rely on the tool name alone — the description is what the model reads.

3. Missing error handling. When a database query fails, return a structured error message, not a stack trace. The AI needs to tell the user something useful, and raw errors leak implementation details.

4. No rate limiting. AI tool calls can happen in loops. If the model calls your tool 50 times in one conversation, you need circuit breakers:

const rateLimiter = new Map<string, number[]>();

function checkRateLimit(userId: string, limit = 30, windowMs = 60000) {
  const now = Date.now();
  const calls = rateLimiter.get(userId) ?? [];
  const recent = calls.filter((t) => now - t < windowMs);

  if (recent.length >= limit) {
    throw new Error(
      `Rate limit exceeded. Max ${limit} calls per minute.`
    );
  }

  recent.push(now);
  rateLimiter.set(userId, recent);
}

5. Not testing with actual AI models. Your tools might look correct in unit tests but confuse the model. Test the full loop: AI model receives tool definitions, decides to call a tool, gets the result, and reasons about it. Adjust descriptions based on how the model actually behaves.

Wrapping Up

Building MCP servers for internal data is about three things:

1. Good tool design — clear descriptions, typed parameters, structured responses

2. Proper access control — authenticate users, scope data access, log everything

3. Production readiness — health checks, rate limiting, error handling, monitoring

The protocol itself is straightforward. The hard work is designing the right abstractions over your internal systems so the AI can use them effectively without leaking data or overwhelming the context window.

Start with one or two high-value tools (employee lookup, document search), test them with real users, and expand from there. The best internal MCP servers grow organically based on what people actually ask the AI.

The full source code from this guide is available on GitHub.

By the end of this guide, you'll have a fully functional application that can:

• Upload and process PDF, DOCX, and TXT files

• Store documents in Supabase Storage

• Generate embeddings using OpenAI

• Perform semantic search across document chunks

• Provide AI-generated answers based on document content

• View and manage uploaded documents

This is a production-ready solution that you can deploy and use immediately.

Table of Contents

• What You'll Learn

• Prerequisites

• Understanding the Technologies

• Project Overview

• Step 1: Create Your Next.js Project

• Step 2: Install Required Dependencies

• Step 3: Set Up Your Supabase Project

• Step 4: Configure Environment Variables

• Step 5: Create the Upload API Route

• Step 6: Create the RAG Search API Route

• Step 7: Create the Documents API Route

• Step 8: Create the Upload Modal Component

• Step 9: Create the PDF Viewer Modal Component

• Step 10: Create the Navigation Component

• Step 11: Create the Home Page (Search Interface)

• Step 12: Create the Documents Page

• Step 13: Test Your Application

• Step 14: Deploy Your Application

• How RAG Search Works

• Troubleshooting Common Issues

• Next Steps

• Conclusion

What You'll Learn

In this handbook, you'll learn how to:

• Set up a Next.js application with TypeScript

• Configure Supabase for database and file storage

• Integrate OpenAI embeddings and chat completions

• Implement document text extraction and chunking

• Build a vector search system using PostgreSQL

• Create a modern UI with React components

• Handle file uploads and storage

• Implement RAG (Retrieval-Augmented Generation) search

Prerequisites

Before you begin, make sure you have:

• Node.js 18 or higher installed on your computer

• A Supabase account (free tier works fine)

• An OpenAI API key

• Basic knowledge of React and TypeScript

• Familiarity with Next.js (helpful but not required)

Understanding the Technologies

Before we dive into building the application, you should understand the key technologies and concepts you'll be working with:

What is RAG (Retrieval-Augmented Generation)?

RAG is an AI pattern that combines information retrieval with text generation. Instead of relying solely on an AI model's training data, RAG retrieves relevant information from your own documents. It then uses that information as context to generate accurate, up-to-date answers. This approach gives you:

• Accuracy: Answers are based on your actual documents, not just the AI's training data

• Transparency: You can see which document sections were used to generate the answer

• Efficiency: Only relevant document chunks are used, reducing token costs

What are Embeddings and Vector Database?

Embeddings are numerical representations of text that capture semantic meaning. When you convert text to an embedding, similar meanings are represented by similar numbers. For example, "dog" and "puppy" would have similar embeddings. Meanwhile, "dog" and "airplane" would have very different ones.

OpenAI's embedding models convert text into vectors. These are arrays of numbers that can be compared mathematically. This allows you to find documents that are semantically similar to a search query. You can find matches even if they don't contain the exact same words.

A vector database is a specialized database designed to store and search through embeddings efficiently. Instead of searching for exact text matches, vector databases use mathematical operations. They use operations like cosine similarity to find the most semantically similar content.

In this tutorial, you'll use Supabase's PostgreSQL database with the pgvector extension. This extension adds vector storage and similarity search capabilities to PostgreSQL. This lets you store embeddings alongside your regular database data. You can also perform fast similarity searches.

What is Text Chunking?

Text chunking is the process of breaking large documents into smaller, manageable pieces. This is necessary for several reasons.

First, AI models have token limits. These are maximum input sizes. Second, smaller chunks allow for more precise retrieval. Third, overlapping chunks ensure context isn't lost at boundaries.

You'll use LangChain's RecursiveCharacterTextSplitter. This tool intelligently splits text while trying to preserve sentence and paragraph boundaries.

What is Supabase?

Supabase is an open-source Firebase alternative. It provides several key features.

You get a PostgreSQL database, which is a powerful, open-source relational database. You also get storage, which is file storage similar to AWS S3. There are real-time features that provide real-time subscriptions to database changes. Finally, there's built-in user authentication.

For this project, you'll use Supabase's database to store document chunks and embeddings. You'll also use Supabase Storage to store the original uploaded files.

What is Tailwind CSS?

Tailwind CSS is a utility-first CSS framework that lets you style your application by applying pre-built utility classes directly in your HTML/JSX. Instead of writing custom CSS, you use classes like bg-blue-600, text-white, and rounded-lg to style elements.

You'll use Tailwind CSS in this project because it speeds up development by providing ready-made styling utilities. It also ensures consistent design across the application. Plus, it makes it easy to create responsive, modern UIs. Finally, it works seamlessly with Next.js.

Now that you understand the core concepts and tools we’ll be using, let's start building the application.

Project Overview

Your RAG search application will consist of:

1. Frontend: Next.js application with React components for uploading documents and searching

2. Backend API Routes: Next.js API routes for handling uploads, searches, and document management

3. Database: Supabase PostgreSQL with vector extension for storing embeddings

4. Storage: Supabase Storage for storing original files

5. AI Integration: OpenAI for generating embeddings and chat completions

The application will have two main pages:

• Search Page: Where users can ask questions about their uploaded documents and get AI-generated answers

• Documents Page: Where users can view all uploaded documents, upload new ones, preview files, and manage their document library

Let's start building!

If you ever get stuck on the source code, you can view it on GitHub here:

https://github.com/mayur9210/rag-search-app

Step 1: Create Your Next.js Project

Start by creating a new Next.js project with TypeScript. Open your terminal and run:

npx create-next-app@latest rag-search-app --typescript --tailwind --app

When prompted, choose the following options:

• TypeScript: Yes

• ESLint: Yes

• Tailwind CSS: Yes

• App Router: Yes (default)

• Customize import alias: No

Navigate into your project directory:

cd rag-search-app

Now that your project is set up, you'll need to install the additional packages required for document processing, AI integration, and database operations.

Step 2: Install Required Dependencies

You'll need several packages for this project. You can install them using npm:

npm install @supabase/supabase-js @langchain/openai @langchain/textsplitters langchain openai mammoth pdf2json

Here's what each package does:

• @supabase/supabase-js: Client library for interacting with Supabase (database and storage)

• @langchain/openai: LangChain integration for OpenAI (helps with text processing)

• @langchain/textsplitters: Text splitting utilities for chunking documents into smaller pieces

• langchain: Core LangChain library (provides AI workflow tools)

• openai: Official OpenAI SDK (for generating embeddings and chat completions)

• mammoth: Converts DOCX files to plain text

• pdf2json: Extracts text from PDF files

Install the TypeScript types for pdf2json:

npm install --save-dev @types/pdf-parse

With all dependencies installed, you're ready to set up your Supabase project, which will handle your database and file storage needs.

Step 3: Set Up Your Supabase Project

Create a Supabase Project

First, you’ll need to create a new Supabase project, which you can do by following these steps:

1. Go to supabase.com and sign in or create an account

2. Click "New Project"

3. Fill in your project details:

   • Name: rag-search-app (or any name you prefer)

   • Database Password: Choose a strong password (save this – you'll need it)

   • Region: Select the region closest to you

4. Click "Create new project" and wait for it to be ready (this takes a few minutes)

Get Your Supabase Credentials

Once your project is ready, go to Settings and then API.

Copy the following values:

• Project URL (this is your NEXT_PUBLIC_SUPABASE_URL)

• anon public key (this is your NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY)

• service_role key (this is your SUPABASE_SERVICE_ROLE_KEY)

Important: Keep your service role key secret. Never expose it in client-side code. It bypasses Row-Level Security (RLS) policies, which is necessary for server-side file uploads but should never be used in browser code.

Set Up the Database Schema

Now you'll set up the database structure to store your documents and embeddings. Go to SQL Editor in your Supabase dashboard and run the following SQL:

-- Enable the vector extension for embeddings
-- This extension allows PostgreSQL to store and search vector data efficiently
CREATE EXTENSION IF NOT EXISTS vector;

-- Create the documents table
-- This table stores document chunks, their metadata, and embeddings
CREATE TABLE documents (
  id BIGSERIAL PRIMARY KEY,
  content TEXT NOT NULL,
  metadata JSONB,
  embedding vector(1536)  -- OpenAI's text-embedding-3-small produces 1536-dimensional vectors
  file_path text null,
  file_url text null,
);

-- Create an index on the embedding column for faster similarity search
-- The ivfflat index speeds up vector similarity queries
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);

-- Create a function for matching documents based on similarity
-- This function finds the most similar document chunks to a query embedding
CREATE OR REPLACE FUNCTION match_documents(
  query_embedding vector(1536),
  match_threshold float,
  match_count int
)
RETURNS TABLE (
  id bigint,
  content text,
  metadata jsonb,
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    documents.id,
    documents.content,
    documents.metadata,
    1 - (documents.embedding <=> query_embedding) AS similarity
  FROM documents
  WHERE 1 - (documents.embedding <=> query_embedding) > match_threshold
  ORDER BY documents.embedding <=> query_embedding
  LIMIT match_count;
END;
$$;

This SQL does the following:

• Enables the vector extension: This adds vector storage and similarity search capabilities to PostgreSQL

• Creates the documents table: Stores document chunks, metadata (file name, type, and so on), and their embeddings

• Creates an index: Speeds up similarity searches on the embedding column

• Creates a match function: Finds the most similar document chunks to a query embedding using cosine similarity

The <=> operator calculates cosine distance between vectors. A smaller distance means more similar content.

Set Up Supabase Storage

You’ll need a storage bucket to store uploaded files. This is separate from the database and holds the original PDF, DOCX, and TXT files.

To set up your storage bucket:

1. Go to Storage in your Supabase dashboard

2. Click New bucket

3. Name it documents

4. Set it to Public (this allows file downloads)

5. Click Create bucket

If you prefer a private bucket, you can use the service role key for server-side operations, which bypasses Row-Level Security policies. For this tutorial, a public bucket is simpler and works well.

Now that your Supabase project is configured, you'll set up your environment variables to connect your Next.js application to Supabase and OpenAI.

Step 4: Configure Environment Variables

Create a .env.local file in your project root:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
OPENAI_API_KEY=your_openai_api_key

Replace the placeholder values with your actual credentials:

• Get Supabase values from Settings → API in your Supabase dashboard

• Get your OpenAI API key from platform.openai.com/api-keys

Security Note: Never commit .env.local to version control. It's already in .gitignore by default, but double-check to ensure your secrets stay secure.

With your environment configured, you're ready to start building the API routes that will handle file uploads, searches, and document management.

Step 5: Create the Upload API Route

Now you'll create the API route that handles file uploads. This route will process uploaded files, extract their text, split them into chunks, generate embeddings, and store everything in your database and storage.

Create src/app/api/upload/route.ts:

import { createClient } from '@supabase/supabase-js';
import OpenAI from 'openai';
import { NextResponse } from 'next/server';
import { RecursiveCharacterTextSplitter } from '@langchain/textsplitters';
import mammoth from 'mammoth';

const url = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const anonKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY!;
const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
const supabaseStorage = createClient(url, serviceKey || anonKey);
const supabase = createClient(url, anonKey);
const openai = new OpenAI();

function safeDecodeURIComponent(str: string): string {
  try { 
    return decodeURIComponent(str); 
  } catch { 
    try { 
      return decodeURIComponent(str.replace(/%/g, '%25')); 
    } catch { 
      return str; 
    } 
  }
}

async function extractTextFromFile(file: File): Promise<string> {
  const buffer = Buffer.from(await file.arrayBuffer());
  const fileName = file.name.toLowerCase();

  if (fileName.endsWith('.pdf')) {
    const PDFParser = (await import('pdf2json')).default;
    return new Promise((resolve, reject) => {
      const pdfParser = new (PDFParser as any)(null, true);
      pdfParser.on('pdfParser_dataError', (err: any) => 
        reject(new Error(`PDF parsing error: ${err.parserError}`))
      );
      pdfParser.on('pdfParser_dataReady', (pdfData: any) => {
        try {
          let fullText = '';
          pdfData.Pages?.forEach((page: any) => 
            page.Texts?.forEach((text: any) => 
              text.R?.forEach((r: any) => 
                r.T && (fullText += safeDecodeURIComponent(r.T) + ' ')
              )
            )
          );
          resolve(fullText.trim());
        } catch (error: any) {
          reject(new Error(`Error extracting text: ${error.message}`));
        }
      });
      pdfParser.parseBuffer(buffer);
    });
  } else if (fileName.endsWith('.docx')) {
    const result = await mammoth.extractRawText({ buffer });
    return result.value;
  } else if (fileName.endsWith('.txt')) {
    return buffer.toString('utf-8');
  } else {
    throw new Error('Unsupported file type. Please upload PDF, DOCX, or TXT files.');
  }
}

export async function POST(req: Request) {
  try {
    const file = (await req.formData()).get('file') as File;
    if (!file) {
      return NextResponse.json({ error: 'No file provided' }, { status: 400 });
    }

    const documentId = crypto.randomUUID();
    const uploadDate = new Date().toISOString();
    const filePath = `${documentId}.${file.name.split('.').pop() || 'bin'}`;

    // Upload file to Supabase Storage
    const fileBuffer = Buffer.from(await file.arrayBuffer());
    const { error: storageError } = await supabaseStorage.storage
      .from('documents')
      .upload(filePath, fileBuffer, {
        contentType: file.type || 'application/octet-stream',
        upsert: false,
      });

    if (storageError) {
      const msg = storageError.message || 'Unknown storage error';
      if (msg.includes('row-level security') || msg.includes('RLS')) {
        return NextResponse.json({ 
          success: false, 
          error: `Storage RLS error: ${msg}. Ensure SUPABASE_SERVICE_ROLE_KEY is set.` 
        }, { status: 500 });
      }
      return NextResponse.json({ 
        success: false, 
        error: `Failed to store file: ${msg}` 
      }, { status: 500 });
    }

    // Get public URL for the file
    const { data: urlData } = supabaseStorage.storage
      .from('documents')
      .getPublicUrl(filePath);

    // Extract text from file
    const text = await extractTextFromFile(file);
    if (!text || text.trim().length === 0) {
      return NextResponse.json({ 
        error: 'Could not extract text from file' 
      }, { status: 400 });
    }

    // Split text into chunks
    // Chunk size of 800 characters with 100-character overlap ensures
    // we don't lose context at chunk boundaries
    const textSplitter = new RecursiveCharacterTextSplitter({
      chunkSize: 800,
      chunkOverlap: 100,
    });
    const chunks = await textSplitter.splitText(text);

    // Process each chunk: generate embedding and store in database
    for (let i = 0; i < chunks.length; i++) {
      const chunk = chunks[i];

      // Generate embedding using OpenAI
      // This converts the text chunk into a 1536-dimensional vector
      const emb = await openai.embeddings.create({
        model: 'text-embedding-3-small',
        input: chunk,
      });

      // Store chunk with embedding in database
      const { error } = await supabase.from('documents').insert({
        content: chunk,
        metadata: { 
          source: file.name,
          document_id: documentId,
          file_name: file.name,
          file_type: file.type || file.name.split('.').pop(),
          file_size: file.size,
          upload_date: uploadDate,
          chunk_index: i,
          total_chunks: chunks.length,
          file_path: filePath,
          file_url: urlData.publicUrl,
        },
        embedding: JSON.stringify(emb.data[0].embedding),
      });

      if (error) {
        return NextResponse.json({ 
          success: false, 
          error: error.message 
        }, { status: 500 });
      }
    }

    return NextResponse.json({ 
      success: true, 
      documentId, 
      fileName: file.name, 
      chunks: chunks.length, 
      textLength: text.length, 
      fileUrl: urlData.publicUrl 
    });
  } catch (error: any) {
    return NextResponse.json({ 
      success: false, 
      error: error.message || 'Failed to process file' 
    }, { status: 500 });
  }
}

This route handles the complete upload workflow:

1. Receives the file from the client via FormData

2. Generates a unique document ID using crypto.randomUUID()

3. Uploads the file to Supabase Storage for safekeeping

4. Extracts text based on file type (PDF, DOCX, or TXT)

5. Splits the text into chunks of 800 characters with 100-character overlap

6. Generates embeddings for each chunk using OpenAI's embedding model

7. Stores each chunk with its embedding and metadata in the database

The overlap between chunks ensures that if a sentence or concept spans a chunk boundary, it won't be lost. Now that you can upload and process documents, let's create the search functionality.

Step 6: Create the RAG Search API Route

This route implements the core RAG functionality: it takes a user's query, finds the most relevant document chunks, and uses them to generate an accurate answer.

Create src/app/api/search/route.ts:

import { createClient } from '@supabase/supabase-js';
import OpenAI from 'openai';
import { NextResponse } from 'next/server';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY!
);
const openai = new OpenAI();

export async function POST(req: Request) {
  try {
    const { query } = await req.json();

    // Generate embedding for the user's query
    // This converts the search query into the same vector space as document chunks
    const emb = await openai.embeddings.create({ 
      model: 'text-embedding-3-small', 
      input: query 
    });

    // Find similar documents using vector similarity search
    // The match_documents function finds the 5 most similar chunks
    const { data: results, error } = await supabase.rpc('match_documents', {
      query_embedding: JSON.stringify(emb.data[0].embedding),
      match_threshold: 0.0,  // Accept any similarity (you can increase this for stricter matching)
      match_count: 5,        // Return top 5 most similar chunks
    });

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    // Combine retrieved chunks into context
    // These chunks will be used as context for the AI to generate an answer
    const context = results?.map((r: any) => r.content).join('\n---\n') || '';

    // Generate answer using OpenAI with retrieved context
    // This is the "Generation" part of RAG
    const completion = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [
        { 
          role: 'system', 
          content: 'You are a helpful assistant. Use the provided context to answer questions. If the answer is not in the context, say you do not know.' 
        },
        { 
          role: 'user', 
          content: `Context: ${context}\n\nQuestion: ${query}` 
        }
      ],
    });

    return NextResponse.json({ 
      answer: completion.choices[0].message.content, 
      sources: results 
    });
  } catch (error: any) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
}

This route implements the RAG pattern. Here's how the complete RAG workflow works:

1. Converts the query to an embedding: The user's question is transformed into the same vector space as your document chunks. This uses the same embedding model (text-embedding-3-small) that processed the documents, ensuring they're in the same "vector space."

2. Searches for similar chunks: Uses the match_documents function to find the 5 most semantically similar document chunks. This uses cosine similarity on the embeddings. Cosine similarity measures the angle between vectors - smaller angles mean more similar content, even if the exact words differ.

3. Uses chunks as context: The retrieved chunks are passed to GPT-4o-mini as context. These chunks contain the most relevant information from your documents.

4. Generates an answer: The AI model generates an answer based on the provided context. The system prompt instructs the AI to only answer based on the provided context, ensuring accuracy and preventing hallucinations.

5. Returns results: Both the answer and source chunks are returned so users can verify the information.

This RAG approach gives you several benefits. First, you get accuracy because answers are based on your actual documents, not just the AI's training data. Second, you get transparency because you can see which document chunks were used to generate each answer. Third, you get efficiency because only relevant chunks are used, which reduces token usage and costs. Finally, you get up-to-date information because you can update your knowledge base by uploading new documents without retraining the AI.

Now let's create the API route for managing documents.

Step 7: Create the Documents API Route

This route handles listing, viewing, downloading, and deleting documents. It serves multiple purposes depending on the query parameters.

Create src/app/api/documents/route.ts:

import { createClient } from '@supabase/supabase-js';
import { NextResponse } from 'next/server';

const url = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const anonKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY!;
const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY || anonKey;
const supabase = createClient(url, anonKey);
const supabaseStorage = createClient(url, serviceKey);

export async function GET(req: Request) {
  try {
    const reqUrl = new URL(req.url);
    const id = reqUrl.searchParams.get('id');
    const file = reqUrl.searchParams.get('file') === 'true';
    const view = reqUrl.searchParams.get('view') === 'true';

    // Handle file download/view
    if (id && file) {
      const { data: documents } = await supabase
        .from('documents')
        .select('metadata')
        .eq('metadata->>document_id', id)
        .limit(1);

      if (!documents || documents.length === 0) {
        return NextResponse.json({ error: 'Document not found' }, { status: 404 });
      }

      const meta = documents[0].metadata;
      const fileName = meta?.file_name || 'document';
      const fileType = meta?.file_type || 'application/octet-stream';
      const filePath = meta?.file_path || `${id}.${fileName.split('.').pop() || 'pdf'}`;

      const { data: fileData, error: downloadError } = await supabaseStorage.storage
        .from('documents')
        .download(filePath);

      if (downloadError || !fileData) {
        return NextResponse.json({ 
          error: downloadError?.message || 'File not stored' 
        }, { status: 404 });
      }

      const buffer = Buffer.from(await fileData.arrayBuffer());
      if (buffer.length === 0) {
        return NextResponse.json({ error: 'File is empty' }, { status: 500 });
      }

      const isPDF = fileType === 'application/pdf' || fileName.toLowerCase().endsWith('.pdf');
      return new NextResponse(new Uint8Array(buffer), {
        headers: {
          'Content-Type': fileType,
          'Content-Disposition': (view && isPDF) 
            ? `inline; filename="${fileName}"` 
            : `attachment; filename="${fileName}"`,
          'Content-Length': buffer.length.toString(),
          ...(view && isPDF ? { 'X-Content-Type-Options': 'nosniff' } : {}),
        },
      });
    }

    // Get single document with text content
    if (id) {
      const { data: chunks, error } = await supabase
        .from('documents')
        .select('content, metadata')
        .eq('metadata->>document_id', id)
        .order('metadata->>chunk_index', { ascending: true });

      if (error || !chunks || chunks.length === 0) {
        return NextResponse.json({ error: 'Document not found' }, { status: 404 });
      }

      const m = chunks[0].metadata || {};
      return NextResponse.json({
        id,
        file_name: m.file_name || 'Unknown',
        file_type: m.file_type || 'unknown',
        file_size: m.file_size || 0,
        upload_date: m.upload_date || new Date().toISOString(),
        total_chunks: chunks.length,
        fullText: chunks.map((c: any) => c.content).join('\n\n'),
        file_url: m.file_url,
        file_path: m.file_path
      });
    }

    // List all documents
    const { data: documents, error } = await supabase
      .from('documents')
      .select('metadata');

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    // Deduplicate documents by document_id
    // Since each document is split into multiple chunks, we need to group them
    const map = new Map();
    documents?.forEach((doc: any) => {
      const m = doc.metadata;
      if (m?.document_id && !map.has(m.document_id)) {
        map.set(m.document_id, {
          id: m.document_id,
          file_name: m.file_name || 'Unknown',
          file_type: m.file_type || 'unknown',
          file_size: m.file_size || 0,
          upload_date: m.upload_date || new Date().toISOString(),
          total_chunks: m.total_chunks || 0,
          file_url: m.file_url,
          file_path: m.file_path,
        });
      }
    });

    return NextResponse.json({ documents: Array.from(map.values()) });
  } catch (error: any) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
}

export async function DELETE(req: Request) {
  try {
    const id = new URL(req.url).searchParams.get('id');
    if (!id) {
      return NextResponse.json({ error: 'Document ID required' }, { status: 400 });
    }

    // Get file path from metadata
    const { data: docs } = await supabase
      .from('documents')
      .select('metadata')
      .eq('metadata->>document_id', id)
      .limit(1);

    const filePath = docs?.[0]?.metadata?.file_path;

    // Delete file from storage
    if (filePath) {
      await supabaseStorage.storage.from('documents').remove([filePath]);
    }

    // Delete all chunks from database
    const { error } = await supabase
      .from('documents')
      .delete()
      .eq('metadata->>document_id', id);

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ success: true, fileDeleted: !!filePath });
  } catch (error: any) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
}

This route handles:

• GET without ID: Lists all documents (deduplicated since each document has multiple chunks)

• GET with ID: Returns document details and full text (all chunks combined)

• GET with ID and file=true: Downloads the original file from storage

• DELETE with ID: Deletes the document and its file from both storage and database

Now that your API routes are complete, let's build the user interface components, starting with the upload modal.

Step 8: Create the Upload Modal Component

The upload modal provides a user-friendly interface for selecting and uploading documents. It handles file selection, upload progress, and displays success or error messages.

Create src/app/components/UploadModal.tsx:

'use client';
import { useState, useEffect } from 'react';

interface UploadModalProps {
  isOpen: boolean;
  onClose: () => void;
  onUploadSuccess?: () => void;
}

export default function UploadModal({ isOpen, onClose, onUploadSuccess }: UploadModalProps) {
  const [file, setFile] = useState<File | null>(null);
  const [uploading, setUploading] = useState(false);
  const [message, setMessage] = useState<{ type: 'success' | 'error'; text: string } | null>(null);

  useEffect(() => {
    document.body.style.overflow = isOpen ? 'hidden' : 'unset';
    if (!isOpen) { 
      setFile(null); 
      setMessage(null); 
    }
    return () => { 
      document.body.style.overflow = 'unset'; 
    };
  }, [isOpen]);

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    if (e.target.files && e.target.files[0]) {
      setFile(e.target.files[0]);
      setMessage(null);
    }
  };

  const handleUpload = async () => {
    if (!file) {
      setMessage({ type: 'error', text: 'Please select a file' });
      return;
    }

    setUploading(true);
    setMessage(null);

    try {
      const formData = new FormData();
      formData.append('file', file);

      const res = await fetch('/api/upload', {
        method: 'POST',
        body: formData,
      });

      const data = await res.json();

      if (data.success) {
        setMessage({
          type: 'success',
          text: `File "${data.fileName}" uploaded successfully! Processed ${data.chunks} chunks.`,
        });
        setFile(null);
        (document.getElementById('upload-file-input') as HTMLInputElement)?.setAttribute('value', '');
        setTimeout(() => { 
          onUploadSuccess?.(); 
          onClose(); 
        }, 1500);
      } else {
        setMessage({ type: 'error', text: data.error || 'Upload failed' });
      }
    } catch (error: any) {
      setMessage({ type: 'error', text: error.message || 'Upload failed' });
    } finally {
      setUploading(false);
    }
  };

  if (!isOpen) return null;

  return (
    <div
      className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-75 p-4"
      onClick={onClose}
    >
      <div
        className="relative bg-white dark:bg-gray-900 rounded-lg shadow-xl w-full max-w-2xl max-h-[90vh] overflow-y-auto"
        onClick={(e) => e.stopPropagation()}
      >
        <div className="flex items-center justify-between p-6 border-b border-gray-200 dark:border-gray-800">
          <h2 className="text-2xl font-semibold text-gray-900 dark:text-gray-100">
            Upload Document
          </h2>
          <button
            onClick={onClose}
            className="p-2 text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800"
            aria-label="Close"
          >
            <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
            </svg>
          </button>
        </div>

        <div className="p-6">
          <div className="mb-6">
            <label htmlFor="upload-file-input" className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
              Select a file (PDF, DOCX, or TXT)
            </label>
            <input
              id="upload-file-input"
              type="file"
              accept=".pdf,.docx,.txt"
              onChange={handleFileChange}
              className="block w-full text-sm text-gray-500
                file:mr-4 file:py-2 file:px-4
                file:rounded-lg file:border-0
                file:text-sm file:font-semibold
                file:bg-blue-50 file:text-blue-700
                hover:file:bg-blue-100
                dark:file:bg-blue-900 dark:file:text-blue-300
                dark:hover:file:bg-blue-800"
            />
          </div>

          {file && (
            <div className="mb-6 p-4 bg-gray-50 dark:bg-gray-800 rounded-lg text-sm text-gray-600 dark:text-gray-400 space-y-1">
              <p><span className="font-medium">Selected:</span> {file.name}</p>
              <p><span className="font-medium">Size:</span> {(file.size / 1024).toFixed(2)} KB</p>
              <p><span className="font-medium">Type:</span> {file.type || file.name.split('.').pop()}</p>
            </div>
          )}

          <button
            onClick={handleUpload}
            disabled={!file || uploading}
            className="w-full bg-blue-600 text-white px-6 py-3 rounded-lg hover:bg-blue-700 disabled:bg-gray-400 disabled:cursor-not-allowed font-medium"
          >
            {uploading ? 'Uploading and Processing...' : 'Upload Document'}
          </button>

          {message && (
            <div
              className={`mt-6 p-4 rounded-lg ${
                message.type === 'success'
                  ? 'bg-green-50 text-green-800 dark:bg-green-900 dark:text-green-200'
                  : 'bg-red-50 text-red-800 dark:bg-red-900 dark:text-red-200'
              }`}
            >
              {message.text}
            </div>
          )}

          <div className="mt-8 p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg text-sm">
            <p className="font-medium text-blue-900 dark:text-blue-200 mb-2">Supported: PDF, DOCX, TXT</p>
            <p className="text-blue-700 dark:text-blue-400">Files will be processed and embedded for RAG search.</p>
          </div>
        </div>
      </div>
    </div>
  );
}

This component provides a clean interface for file uploads with proper error handling and user feedback. Next, let's create the PDF viewer component for previewing documents.

Step 9: Create the PDF Viewer Modal Component

The PDF viewer modal allows users to preview PDFs and view extracted text from any document. It's particularly useful for verifying that documents were processed correctly.

Create src/app/components/PDFViewerModal.tsx:

'use client';
import { useEffect, useState } from 'react';

interface PDFViewerModalProps {
  isOpen: boolean;
  onClose: () => void;
  fileUrl: string;
  fileName: string;
  documentId?: string;
  isPDF?: boolean;
}

export default function PDFViewerModal({ 
  isOpen, 
  onClose, 
  fileUrl, 
  fileName, 
  documentId, 
  isPDF = true 
}: PDFViewerModalProps) {
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);
  const [activeTab, setActiveTab] = useState<'preview' | 'content'>('preview');
  const [text, setText] = useState<string>('');
  const [textLoading, setTextLoading] = useState(false);
  const [textError, setTextError] = useState<string | null>(null);

  useEffect(() => {
    document.body.style.overflow = isOpen ? 'hidden' : 'unset';
    if (isOpen) { 
      setError(null); 
      setLoading(true); 
      setActiveTab(isPDF ? 'preview' : 'content'); 
      setText(''); 
      setTextError(null); 
    }
    return () => { 
      document.body.style.overflow = 'unset'; 
    };
  }, [isOpen, isPDF]);

  useEffect(() => {
    if (isOpen && documentId && activeTab === 'content' && !text && !textLoading && !textError) {
      fetchDocumentText();
    }
  }, [isOpen, documentId, activeTab, text, textLoading, textError]);

  useEffect(() => {
    if (isOpen && fileUrl && isPDF) {
      fetch(fileUrl, { method: 'GET', headers: { 'Accept': 'application/json' } })
        .then(async res => {
          if (res.headers.get('content-type')?.includes('application/json')) {
            const data = await res.json();
            throw new Error(data.error || 'File not available');
          }
          if (!res.ok) throw new Error(`Failed to load: ${res.status}`);
          setLoading(false);
        })
        .catch(err => {
          setError(err.message || 'Failed to load PDF');
          setLoading(false);
        });
    } else if (isOpen && !isPDF) {
      setLoading(false);
    }
  }, [isOpen, fileUrl, isPDF]);

  const fetchDocumentText = async () => {
    if (!documentId) return;
    setTextLoading(true); 
    setTextError(null);
    try {
      const res = await fetch(`/api/documents?id=${documentId}`);
      const data = await res.json();
      if (data.error) {
        setTextError(data.error);
      } else {
        setText(data.fullText || 'No text content available');
      }
    } catch (err) {
      setTextError(err instanceof Error ? err.message : 'Failed to fetch document text');
    } finally {
      setTextLoading(false);
    }
  };

  if (!isOpen) return null;

  return (
    <div
      className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-75 p-4"
      onClick={onClose}
    >
      <div
        className="relative bg-white dark:bg-gray-900 rounded-lg shadow-xl w-full max-w-6xl h-[90vh] flex flex-col"
        onClick={(e) => e.stopPropagation()}
      >
        <div className="flex flex-col border-b border-gray-200 dark:border-gray-800">
          <div className="flex items-center justify-between p-4">
            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 truncate flex-1 mr-4">
              {fileName}
            </h2>
            <div className="flex items-center gap-2">
              <button
                onClick={onClose}
                className="p-2 text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800"
                aria-label="Close"
              >
                <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
                </svg>
              </button>
            </div>
          </div>

          {isPDF && (
            <div className="flex border-t border-gray-200 dark:border-gray-800">
              {(['preview', 'content'] as const).map(tab => (
                <button 
                  key={tab} 
                  onClick={() => setActiveTab(tab)} 
                  className={`flex-1 px-4 py-3 text-sm font-medium transition-colors ${
                    activeTab === tab 
                      ? 'text-blue-600 dark:text-blue-400 border-b-2 border-blue-600 dark:border-blue-400 bg-blue-50 dark:bg-blue-900/20' 
                      : 'text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-800'
                  }`}
                >
                  {tab.charAt(0).toUpperCase() + tab.slice(1)}
                </button>
              ))}
            </div>
          )}
        </div>

        <div className="flex-1 overflow-hidden">
          {isPDF && activeTab === 'preview' && (
            <div className="h-full overflow-hidden">
              {error ? (
                <div className="flex flex-col items-center justify-center h-full p-8">
                  <div className="bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg p-6 max-w-md">
                    <h3 className="text-lg font-semibold text-yellow-800 dark:text-yellow-200 mb-2">
                      PDF File Not Available
                    </h3>
                    <p className="text-yellow-700 dark:text-yellow-300 mb-4">{error}</p>
                    {documentId && (
                      <button 
                        onClick={() => setActiveTab('content')} 
                        className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 font-medium"
                      >
                        View Extracted Text Instead
                      </button>
                    )}
                  </div>
                </div>
              ) : loading ? (
                <div className="flex items-center justify-center h-full">
                  <p className="text-gray-500 dark:text-gray-400">Loading PDF...</p>
                </div>
              ) : (
                <iframe
                  src={`${fileUrl}${fileUrl.includes('?') ? '&' : '?'}view=true#toolbar=1&navpanes=0&scrollbar=1`}
                  className="w-full h-full border-0"
                  title={fileName}
                  allow="fullscreen"
                  onError={() => setError('Failed to load PDF')}
                />
              )}
            </div>
          )}

          {(!isPDF || activeTab === 'content') && (
            <div className="h-full overflow-auto p-6">
              {textLoading ? (
                <div className="flex items-center justify-center h-full">
                  <p className="text-gray-500 dark:text-gray-400">Loading...</p>
                </div>
              ) : textError ? (
                <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4">
                  <p className="text-red-800 dark:text-red-200">Error: {textError}</p>
                </div>
              ) : (
                <div className="space-y-4">
                  <p className="text-sm text-gray-500 dark:text-gray-400">
                    Formatting may be inconsistent from source.
                  </p>
                  <pre className="whitespace-pre-wrap text-sm text-gray-800 dark:text-gray-200 font-mono bg-gray-50 dark:bg-gray-800 p-4 rounded-lg">
                    {text || 'No text content available'}
                  </pre>
                </div>
              )}
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

This component provides a full-screen modal for viewing PDFs and extracted text, with tabs to switch between preview and text content. Now let's create a simple navigation component to tie everything together.

Step 10: Create the Navigation Component

The navigation component provides easy access to the Search and Documents pages. It highlights the current page and provides a clean, consistent navigation experience.

Create src/app/components/Navigation.tsx:

'use client';
import Link from 'next/link';
import { usePathname } from 'next/navigation';

export default function Navigation() {
  const pathname = usePathname();

  const navItems = [
    { href: '/', label: 'Search' },
    { href: '/documents', label: 'Documents' },
  ];

  return (
    <nav className="border-b border-gray-200 dark:border-gray-800 mb-8">
      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
        <div className="flex space-x-8">
          {navItems.map((item) => (
            <Link
              key={item.href}
              href={item.href}
              className={`py-4 px-1 border-b-2 font-medium text-sm ${
                pathname === item.href
                  ? 'border-blue-500 text-blue-600 dark:text-blue-400'
                  : 'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300 dark:text-gray-400 dark:hover:text-gray-300'
              }`}
            >
              {item.label}
            </Link>
          ))}
        </div>
      </div>
    </nav>
  );
}

With navigation in place, let's create the main search page where users can query their documents.

Step 11: Create the Home Page (Search Interface)

The search page is the main interface where users ask questions about their uploaded documents. It displays the AI-generated answers along with source citations, allowing users to verify the information.

Update src/app/page.tsx:

'use client';
import { useState } from 'react';
import Navigation from './components/Navigation';

export default function Home() {
  const [query, setQuery] = useState('');
  const [answer, setAnswer] = useState('');
  const [loading, setLoading] = useState(false);
  const [sources, setSources] = useState<any[]>([]);

  const handleSearch = async () => {
    if (!query.trim()) return;
    setLoading(true); 
    setAnswer(''); 
    setSources([]);
    try {
      const res = await fetch('/api/search', { 
        method: 'POST', 
        headers: { 'Content-Type': 'application/json' }, 
        body: JSON.stringify({ query }) 
      });
      const data = await res.json();
      if (data.error) {
        setAnswer(`Error: ${data.error}`);
      } else { 
        setAnswer(data.answer || 'No answer generated'); 
        setSources(data.sources || []); 
      }
    } catch (error: any) {
      setAnswer(`Error: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };

  const handleKeyPress = (e: React.KeyboardEvent) => {
    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
      handleSearch();
    }
  };

  return (
    <div className="min-h-screen">
      <Navigation />
      <main className="max-w-4xl mx-auto p-8">
        <h1 className="text-3xl font-bold mb-6">RAG Search</h1>

        <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-lg p-6 shadow-sm mb-6">
          <textarea 
            className="w-full p-4 border border-gray-300 dark:border-gray-700 rounded-lg shadow-sm bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 resize-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
            placeholder="Ask a question about your uploaded documents..."
            value={query}
            onChange={(e) => setQuery(e.target.value)}
            onKeyDown={handleKeyPress}
            rows={4}
          />
          <button 
            onClick={handleSearch}
            className="mt-4 bg-blue-600 text-white px-8 py-3 rounded-lg hover:bg-blue-700 disabled:bg-gray-400 disabled:cursor-not-allowed font-medium"
            disabled={loading || !query.trim()}
          >
            {loading ? 'Searching...' : 'Search'}
          </button>
          <p className="mt-2 text-sm text-gray-500 dark:text-gray-400">
            Press Cmd/Ctrl + Enter to search
          </p>
        </div>

        {answer && (
          <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-lg p-6 shadow-sm mb-6">
            <h2 className="text-xl font-semibold mb-3">Answer:</h2>
            <p className="text-gray-800 dark:text-gray-200 leading-relaxed whitespace-pre-wrap">
              {answer}
            </p>
          </div>
        )}

        {sources && sources.length > 0 && (
          <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-lg p-6 shadow-sm">
            <h2 className="text-xl font-semibold mb-3">Sources ({sources.length}):</h2>
            <div className="space-y-3">
              {sources.map((source, index) => (
                <div
                  key={index}
                  className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700"
                >
                  <p className="text-sm text-gray-600 dark:text-gray-400 mb-1">
                    <span className="font-medium">Source:</span>{' '}
                    {source.metadata?.source || source.metadata?.file_name || 'Unknown'}
                  </p>
                  <p className="text-sm text-gray-800 dark:text-gray-200 line-clamp-3">
                    {source.content}
                  </p>
                </div>
              ))}
            </div>
          </div>
        )}
      </main>
    </div>
  );
}

This page provides a clean search interface with a textarea for queries, a search button, and sections to display answers and source citations. The sources section helps users verify where the information came from, which is crucial for trust and accuracy. Now let's create the documents management page.

Step 12: Create the Documents Page

The documents page serves as your document library. It displays all uploaded documents in a table format, shows metadata like file size and chunk count, and provides actions to preview, download, or delete documents. This page is essential for managing your document collection and verifying uploads.

Create src/app/documents/page.tsx:

'use client';
import { useState, useEffect } from 'react';
import Navigation from '../components/Navigation';
import PDFViewerModal from '../components/PDFViewerModal';
import UploadModal from '../components/UploadModal';

interface Document {
  id: string;
  file_name: string;
  file_type: string;
  file_size: number;
  upload_date: string;
  total_chunks: number;
  file_url?: string;
  file_path?: string;
}

export default function DocumentsPage() {
  const [documents, setDocuments] = useState<Document[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [showPDFModal, setShowPDFModal] = useState(false);
  const [selectedPDF, setSelectedPDF] = useState<{ url: string; name: string; id?: string; isPDF?: boolean } | null>(null);
  const [deletingId, setDeletingId] = useState<string | null>(null);
  const [showUploadModal, setShowUploadModal] = useState(false);

  useEffect(() => {
    fetchDocuments();
  }, []);

  const fetchDocuments = async () => {
    try {
      setLoading(true);
      const res = await fetch('/api/documents');
      const data = await res.json();
      if (data.error) {
        setError(data.error);
      } else {
        setDocuments(data.documents || []);
      }
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Failed to fetch documents');
    } finally {
      setLoading(false);
    }
  };

  const formatDate = (s: string) => {
    try {
      const d = new Date(s);
      return isNaN(d.getTime()) 
        ? s 
        : d.toLocaleString('en-US', { 
            year: 'numeric', 
            month: 'short', 
            day: 'numeric', 
            hour: '2-digit', 
            minute: '2-digit', 
            hour12: true 
          });
    } catch { 
      return s; 
    }
  };

  const formatFileSize = (b: number) => 
    b < 1024 
      ? `${b} B` 
      : b < 1024 * 1024 
        ? `${(b / 1024).toFixed(2)} KB` 
        : `${(b / (1024 * 1024)).toFixed(2)} MB`;

  const handleDelete = async (id: string, name: string) => {
    if (!confirm(`Delete "${name}"? This will permanently delete the document, embeddings, and file.`)) {
      return;
    }
    setDeletingId(id);
    try {
      const res = await fetch(`/api/documents?id=${id}`, { method: 'DELETE' });
      const data = await res.json();
      if (data.error) {
        alert(`Error: ${data.error}`);
      } else {
        setDocuments(documents.filter(doc => doc.id !== id));
      }
    } catch (err) {
      alert(err instanceof Error ? err.message : 'Failed to delete');
    } finally {
      setDeletingId(null);
    }
  };

  return (
    <div className="min-h-screen">
      <Navigation />
      <main className="max-w-7xl mx-auto p-8">
        <div className="flex items-center justify-between mb-6">
          <h1 className="text-3xl font-bold">Documents</h1>
          <button
            onClick={() => setShowUploadModal(true)}
            className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 font-medium"
          >
            Upload Document
          </button>
        </div>

        {loading ? (
          <div className="text-center py-12">
            <p className="text-gray-500 dark:text-gray-400">Loading documents...</p>
          </div>
        ) : error ? (
          <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4">
            <p className="text-red-800 dark:text-red-200">Error: {error}</p>
          </div>
        ) : documents.length === 0 ? (
          <div className="bg-gray-50 dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg p-12 text-center">
            <p className="text-gray-500 dark:text-gray-400 mb-4">No documents uploaded yet.</p>
            <button
              onClick={() => setShowUploadModal(true)}
              className="text-blue-600 dark:text-blue-400 hover:underline font-medium"
            >
              Upload your first document
            </button>
          </div>
        ) : (
          <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-lg shadow-sm overflow-hidden">
            <div className="overflow-x-auto">
              <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-800">
                <thead className="bg-gray-50 dark:bg-gray-800">
                  <tr>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      File Name
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Type
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Size
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Chunks
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Upload Date
                    </th>
                    <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
                      Actions
                    </th>
                  </tr>
                </thead>
                <tbody className="bg-white dark:bg-gray-900 divide-y divide-gray-200 dark:divide-gray-800">
                  {documents.map((doc) => (
                    <tr key={doc.id} className="hover:bg-gray-50 dark:hover:bg-gray-800">
                      <td className="px-6 py-4 whitespace-nowrap">
                        <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
                          {doc.file_name}
                        </div>
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap">
                        <span className="px-2 inline-flex text-xs leading-5 font-semibold rounded-full bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-200">
                          {doc.file_type || 'unknown'}
                        </span>
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-500 dark:text-gray-400">
                        {formatFileSize(doc.file_size)}
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-500 dark:text-gray-400">
                        {doc.total_chunks}
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-500 dark:text-gray-400">
                        {formatDate(doc.upload_date)}
                      </td>
                      <td className="px-6 py-4 whitespace-nowrap text-sm font-medium">
                        <div className="flex gap-3 items-center">
                          {doc.file_name.toLowerCase().endsWith('.pdf') ? (
                            <button 
                              onClick={() => {
                                const pdfUrl = doc.file_url 
                                  ? `${doc.file_url}?view=true` 
                                  : `/api/documents?id=${doc.id}&file=true&view=true`;
                                setSelectedPDF({ url: pdfUrl, name: doc.file_name, id: doc.id });
                                setShowPDFModal(true);
                              }} 
                              className="text-blue-600 hover:text-blue-900 dark:text-blue-400 dark:hover:text-blue-300"
                            >
                              Preview
                            </button>
                          ) : (
                            <>
                              <button 
                                onClick={() => {
                                  setSelectedPDF({ 
                                    url: doc.file_url || `/api/documents?id=${doc.id}&file=true`, 
                                    name: doc.file_name, 
                                    id: doc.id, 
                                    isPDF: false 
                                  });
                                  setShowPDFModal(true);
                                }} 
                                className="text-blue-600 hover:text-blue-900 dark:text-blue-400 dark:hover:text-blue-300"
                              >
                                View
                              </button>
                              {(doc.file_url || doc.file_path) && (
                                <a 
                                  href={doc.file_url || `/api/documents?id=${doc.id}&file=true`} 
                                  download={doc.file_name}
                                  className="text-green-600 hover:text-green-900 dark:text-green-400 dark:hover:text-green-300" 
                                  target="_blank" 
                                  rel="noopener noreferrer"
                                >
                                  Download
                                </a>
                              )}
                            </>
                          )}
                          <button 
                            onClick={() => handleDelete(doc.id, doc.file_name)} 
                            disabled={deletingId === doc.id}
                            className="text-red-600 hover:text-red-900 dark:text-red-400 dark:hover:text-red-300 disabled:opacity-50 disabled:cursor-not-allowed"
                          >
                            {deletingId === doc.id ? 'Deleting...' : 'Delete'}
                          </button>
                        </div>
                      </td>
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>
          </div>
        )}

        {selectedPDF && (
          <PDFViewerModal 
            isOpen={showPDFModal} 
            onClose={() => { 
              setShowPDFModal(false); 
              setSelectedPDF(null); 
            }}
            fileUrl={selectedPDF.url} 
            fileName={selectedPDF.name} 
            documentId={selectedPDF.id} 
            isPDF={selectedPDF.isPDF !== false} 
          />
        )}
        <UploadModal 
          isOpen={showUploadModal} 
          onClose={() => setShowUploadModal(false)} 
          onUploadSuccess={fetchDocuments} 
        />
      </main>
    </div>
  );
}

This page provides a comprehensive document management interface with a table showing all documents, their metadata, and action buttons for preview, download, and deletion. The page automatically refreshes after uploads and handles loading and error states gracefully.

Now that all your components and pages are built, let's test the complete application.

Step 13: Test Your Application

Start your development server:

npm run dev

Open http://localhost:3000 in your browser.

Test the Upload Flow

1. Navigate to the Documents page

2. Click "Upload Document"

3. Select a PDF, DOCX, or TXT file

4. Wait for the upload and processing to complete (this may take a moment as embeddings are generated)

5. You should see your document in the list with its metadata:

Test the Search Flow

1. Navigate to the Search page (or click "Search" in the navigation)

2. Make sure you've uploaded at least one document first

3. Type a question about your uploaded document (for example, "What is this document about?" or ask about specific content)

4. Click "Search" or press Cmd/Ctrl + Enter

5. You should see an AI-generated answer with source citations showing which document chunks were used

Once the embedding is done, you can navigate to search and look for the sample test command based on the documents you have uploaded. You can also check the source from which the search results were pulled.

Test Document Management

1. On the Documents page, click "Preview" or "View" on a document

2. Try downloading a document

3. Test deleting a document (be careful - this is permanent)

If everything works correctly, you're ready to deploy your application!

Step 14: Deploy Your Application

Deploy to Vercel

Vercel is the easiest way to deploy Next.js applications and is made by the creators of Next.js:

To get started, you’ll need to push your code to GitHub. So go ahead and create a repository and push your code.

Then go to vercel.com and sign in with your GitHub account. Click "New Project" and import your GitHub repository.

Add your environment variables in the project settings:

• NEXT_PUBLIC_SUPABASE_URL

• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY

• SUPABASE_SERVICE_ROLE_KEY

• OPENAI_API_KEY

Then click "Deploy", and your application will be live in minutes! Vercel automatically builds and deploys your Next.js application, and you'll get a URL like your-app.vercel.app.

Important Deployment Notes

• Make sure all environment variables are set in your Vercel project settings

• The service role key is required for file uploads to work

• Supabase Storage bucket should be accessible (public or with proper RLS policies)

• Your OpenAI API key should have sufficient credits

How RAG Search Works

Your application uses the RAG (Retrieval-Augmented Generation) pattern. This combines information retrieval with AI text generation. Here's how it works step by step:

1. Document processing: When you upload a document, it's split into chunks. These are typically 800 characters each with 100-character overlap. Each chunk gets an embedding. This is a 1536-dimensional vector that represents its semantic meaning.

2. Storage: Embeddings are stored in a vector database. This is PostgreSQL with the pgvector extension. They're stored alongside the original text chunks. The original files are stored in Supabase Storage.

3. Query processing: When you search, your query is converted into an embedding. It uses the same model that processed the documents. This ensures the query and documents are in the same "vector space."

4. Similarity search: The system finds the most similar document chunks. It uses cosine similarity on the embeddings. Cosine similarity measures the angle between vectors. Smaller angles mean more similar content, even if the exact words differ.

5. Answer generation: The retrieved chunks are used as context for an AI model. This model is GPT-4o-mini. It generates an accurate answer. The system prompt instructs the AI to only answer based on the provided context. This ensures accuracy.

This approach gives you several benefits.

First, you get accuracy. Answers are based on your actual documents, not just the AI's training data. Second, you get transparency. You can see which document chunks were used to generate each answer. Third, you get efficiency. Only relevant chunks are used, which reduces token usage and costs. Finally, you get up-to-date information. You can update your knowledge base by uploading new documents without retraining the AI.

Troubleshooting Common Issues

"Storage RLS error" when uploading

This means your SUPABASE_SERVICE_ROLE_KEY is not set or incorrect. Make sure the key is in your .env.local file for local development. Also make sure you're using the service role key, not the anon key. Finally, make sure the key is correctly set in your deployment environment, such as Vercel.

"Failed to extract text from file"

Make sure your file is a valid PDF, DOCX, or TXT file. Check that the file isn't corrupted. For PDFs, ensure they contain extractable text. Scanned PDFs with only images won't work without OCR.

"No answer generated"

Make sure you've uploaded at least one document. Try a different query that's more likely to match your documents. Check that embeddings were successfully created. You can verify this in your Supabase database.

Vector similarity search not working

Ensure the vector extension is enabled in Supabase. You can do this by running CREATE EXTENSION IF NOT EXISTS vector;. Verify the match_documents function exists in your database. You can check this in the SQL Editor. Check that embeddings are being stored correctly. They should be JSON strings in the embedding column.

Slow search or upload times

Large documents take longer to process. This is because more chunks mean more embedding API calls. Consider reducing chunk size or processing documents in batches. Also check your OpenAI API rate limits.

Next Steps

Now that you have a working RAG search application, you can extend it with additional features. Here are some examples of useful features you could add:

• You can add more file types by extending the text extraction to support Markdown, HTML, or other formats.

• You can improve chunking by experimenting with different chunk sizes, overlap strategies, or semantic chunking.

• You can add authentication to protect your documents with user authentication using Supabase Auth.

• You can enhance the UI by adding features like search history, document tags, or advanced filters.

• You can optimize performance by adding caching, pagination, or streaming responses.

• You can add filters to allow users to search within specific documents or date ranges.

• Finally, you can improve search by adding hybrid search, which combines keyword and semantic search, or reranking.

Conclusion

You've built a complete RAG search application from scratch. This application demonstrates modern web development with Next.js and TypeScript. It shows vector database operations with Supabase and pgvector. It demonstrates AI integration with OpenAI embeddings and chat completions. It includes file handling and storage with Supabase Storage. Finally, it features a production-ready user interface with Tailwind CSS.

The RAG pattern you've implemented is used by many production applications. These include chatbots, knowledge bases, document search systems, and AI assistants. You now have the foundation to build more advanced features on top of this.

The skills you've learned are highly valuable in today's AI-driven development landscape. You've learned to work with embeddings, vector databases, and the RAG pattern. You can apply these concepts to build intelligent search systems, document Q&A applications, or AI-powered knowledge bases.

You will build a production-ready AI chatbot widget that you can embed on any website with a single script tag. It’ll be similar to Intercom or Drift – but it’s completely free and under your control.

By the end, you will have a chatbot that:

• Streams AI responses in real-time for a natural typing effect

• Answers questions from your FAQ using RAG (Retrieval Augmented Generation)

• Remembers conversations across page reloads

• Supports dark and light modes

• Works on any website with one line of code

Table of Contents

• Prerequisites

• What You Will Build

• How to Set Up the Project

• How to Configure Wrangler

• How to Build the Backend Worker

• How to Set Up Tailwind CSS

• How to Build the Frontend Widget

• Create the Demo Page

• How to Run it in Your Local System

• How to Deploy to Cloudflare

• How to Embed the Widget on Any Website

• How to Customize Your Chatbot

• Conclusion

Prerequisites

Before you start, make sure you have:

• A Cloudflare account (the free tier works perfectly)

• Node.js version 18 or higher installed on your computer

• Basic knowledge of JavaScript

You do not need any prior experience with Cloudflare Workers.

What You Will Build

Your chatbot will have two main parts:

1. Backend Worker (src/index.js): Handles chat requests, manages sessions, and connects to AI

2. Frontend Widget (public/widget.js): The embeddable UI that users interact with

You will use four Cloudflare services:

• Workers AI: Powers the AI responses using Meta's Llama 3 model

• Vectorize: Stores and searches your FAQ for relevant context (this is the RAG part)

• KV: Persists conversation history between sessions

• Workers: Runs your serverless backend at the edge

How to Set Up the Project

First, create a new Cloudflare Workers project. Open your terminal and run the following command.

When it asks you for the programming language, select javascript, and when it asks, "Do you want to deploy your application?" select no, since we’re going to deploy at the end.

npm create cloudflare@latest ai-chatbot-widget -- --type=hello-world

Navigate into your new project directory:

cd ai-chatbot-widget

And install the required development dependencies:

npm install --save-dev tailwindcss autoprefixer postcss wrangler

Your project is now ready for development.

How to Configure Wrangler

Wrangler is Cloudflare's command-line tool for developing and deploying Workers. You need to configure it to use the required services.

A Cloudflare Worker is a serverless function that runs on Cloudflare's global edge network. Unlike traditional servers that run in a single location, Workers execute as close to your users as possible using more than 300 data centers worldwide. This results in faster response times and lower latency. You just write the JavaScript code, and Cloudflare takes care of all the infrastructure, scaling, and deployment.

Create Resources (One-Time Setup)

The following resources are created via the Wrangler CLI (recommended for automation).

First, install Wrangler (if you don’t have it already):

npm install -g wrangler

To login, use wrangler login. This command will open a Cloudflare browser tab where you will need to authorize.

Create a vectorize index (for RAG):

A vectorize index is a vector database that lets you perform semantic search. Instead of searching for exact keyword matches (like in traditional databases), Vectorize finds content based on meaning.

Here's how it works: You convert your FAQ questions and answers into numerical vectors (called embeddings) using an AI model. When a user asks a question, the chatbot converts that question into a vector and finds the FAQ entries with the most similar vectors. This is the "RAG" (Retrieval Augmented Generation) technique, which augments the AI's response with relevant context from your knowledge base.

npx wrangler vectorize create faq-vectors --dimensions=768 --metric=cosine

Create KV namespace (for session history):

KV (Key-Value) storage is Cloudflare's globally distributed database for storing simple data. Think of it like a giant dictionary: you store data using a key (the session ID) and retrieve it later using that same key.

For your chatbot, KV stores each user's conversation history. When a user returns to your website, the chatbot retrieves their session from KV and remembers what they talked about before.

npx wrangler kv namespace create CHAT_SESSIONS

Note the id from the output as you'll add it in the wrangler.jsonc file.

Create a file called wrangler.jsonc in your project root (you just need to replace YOUR_KV_NAMESPACE_ID with the ID that you received in the last step):

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ai-chatbot-widget",
  "main": "src/index.js",
  "compatibility_date": "2025-12-23",
  "observability": {
    "enabled": true
  },
  "assets": {
    "directory": "./public",
    "binding": "ASSETS"
  },
  "ai": {
    "binding": "AI"
  },
  "vectorize": [
    {
      "binding": "VECTORIZE",
      "index_name": "faq-vectors"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "CHAT_SESSIONS",
      "id": "YOUR_KV_NAMESPACE_ID"
    }
  ]
}

This configuration file tells Wrangler which Cloudflare services your Worker needs access to.

Let me explain the key bindings:

• ASSETS: Serves static files (like your widget JavaScript and CSS) from the public folder

• AI: Connects to Cloudflare's Workers AI for running machine learning models

• VECTORIZE: Links to your Vectorize index for storing and searching FAQ embeddings

• CHAT_SESSIONS: Connects to a KV namespace for storing conversation history

How to Build the Backend Worker

The backend Worker is the brain of your chatbot. It handles incoming chat messages, searches your FAQ for relevant context, sends the conversation to the AI, streams the response back to the user, and saves everything to KV for later.

Create the file src/index.js with this code:

/** AI Chatbot Widget - Cloudflare Worker */
const SYS = `You are a helpful customer support assistant. Be friendly, professional, and concise. Use the FAQ context to give accurate answers. If you don't know something, say so.`;
const TTL = 30*24*60*60;
const cors = { 'Access-Control-Allow-Origin': '*' };
const json = (d, s=200, h={}) => new Response(JSON.stringify(d), { status: s, headers: { 'Content-Type': 'application/json', ...cors, ...h } });
const cookie = r => r.headers.get('Cookie')?.match(/chatbot_session=([^;]+)/)?.[1];

async function faq(env, q) {
  try {
    const e = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [q] });
    if (!e.data) return '';
    const r = await env.VECTORIZE.query(e.data[0], { topK: 3, returnMetadata: 'all' });
    return r.matches.map(m => `Q: ${m.metadata?.question}\nA: ${m.metadata?.answer}`).join('\n\n');
  } catch { return ''; }
}

async function chat(req, env) {
  if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
  const { message } = await req.json();
  if (!message?.trim()) return json({ error: 'Message required' }, 400);
  let sid = cookie(req), isNew = !sid;
  let sess = sid ? await env.CHAT_SESSIONS.get(sid, 'json') : null;
  if (!sess) { sid = 'sess_' + crypto.randomUUID(); sess = { id: sid, messages: [], createdAt: Date.now(), updatedAt: Date.now() }; isNew = true; }
  sess.messages.push({ role: 'user', content: message.trim(), timestamp: Date.now() });
  const ctx = await faq(env, message);
  const msgs = [{ role: 'system', content: SYS + (ctx ? `\n\nFAQ:\n${ctx}` : '') }, ...sess.messages.slice(-10).map(m => ({ role: m.role, content: m.content }))];
  const stream = await env.AI.run('@cf/meta/llama-3-8b-instruct', { messages: msgs, stream: true });
  let full = '';
  const { readable, writable } = new TransformStream({
    transform(chunk, ctrl) {
      for (const ln of new TextDecoder().decode(chunk).split('\n'))
        if (ln.startsWith('data: ') && ln.slice(6) !== '[DONE]') try { full += JSON.parse(ln.slice(6)).response || ''; } catch {}
      ctrl.enqueue(chunk);
    },
    async flush() {
      if (full) { sess.messages.push({ role: 'assistant', content: full, timestamp: Date.now() }); sess.updatedAt = Date.now(); await env.CHAT_SESSIONS.put(sid, JSON.stringify(sess), { expirationTtl: TTL }); }
    }
  });
  stream.pipeTo(writable);
  return new Response(readable, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', ...cors, ...(isNew ? { 'Set-Cookie': `chatbot_session=${sid}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${TTL}` } : {}) } });
}

async function seed(req, env) {
  if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
  const faqs = [
    ['How long does shipping take?', 'Standard 5-7 days, Express 2-3 days, Same-day in select areas.'],
    ['What is your return policy?', '30-day returns for unused items. Electronics 15 days if defective.'],
    ['Do you offer free shipping?', 'Yes! Orders over $50 get free standard shipping.'],
    ['How can I track my order?', 'Check your email for tracking or log into your account.'],
    ['What payment methods do you accept?', 'Visa, Mastercard, Amex, PayPal, Apple Pay, Google Pay.'],
    ['Do you have a warranty?', 'All products have manufacturer warranty. Extended plans available.'],
    ['Can I cancel my order?', 'Within 1 hour if not processed. Otherwise return after delivery.'],
    ['Do you ship internationally?', 'Yes, 50+ countries. 7-14 days. Duties paid by customer.'],
  ];
  try {
    const vecs = await Promise.all(faqs.map(async ([q,a], i) => {
      const e = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [q+' '+a] });
      return { id: `faq-${i+1}`, values: e.data?.[0] || [], metadata: { question: q, answer: a } };
    }));
    await env.VECTORIZE.upsert(vecs);
    return json({ success: true, count: faqs.length });
  } catch { return json({ error: 'Seed failed' }, 500); }
}

export default {
  async fetch(req, env) {
    const p = new URL(req.url).pathname;
    if (req.method === 'OPTIONS') return new Response(null, { headers: { ...cors, 'Access-Control-Allow-Methods': 'GET,POST,OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type' } });
    if (p === '/api/chat') return chat(req, env);
    if (p === '/api/history') { const s = cookie(req); return json({ messages: s ? (await env.CHAT_SESSIONS.get(s, 'json'))?.messages || [] : [] }); }
    if (p === '/api/seed') return seed(req, env);
    if (p === '/api/health') return json({ status: 'ok' });
    return env.ASSETS.fetch(req);
  }
};

Let me break down the key parts of this code:

• Session management: The cookie function extracts the session ID from the user's browser cookies. When a user first chats, the Worker generates a unique session ID, stores it in an HTTP-only cookie, and saves the conversation history to KV. On subsequent visits, the Worker retrieves the session and continues the conversation.

  RAG with Vectorize: The faq function implements RAG. It converts the user's question into a vector embedding using the BGE model, then queries Vectorize for the three most similar FAQ entries. This relevant context is added to the AI prompt, helping the AI give accurate, grounded answers instead of making things up.

  Streaming responses: The chat function uses a TransformStream to process the AI response as it streams. Each token is passed through to the client immediately, creating a natural typing effect. When the stream ends, the complete response is saved to KV.

  Seeding FAQs: The seed function populates your FAQ database. It converts each question-answer pair into a vector embedding and stores it in Vectorize. You only need to call this once after deploying.

Now that your backend is ready, let's build the frontend. But first, you need to set up Tailwind CSS to style your widget.

How to Set Up Tailwind CSS

Your chatbot widget needs to look polished and professional. To achieve this, you will use Tailwind CSS which is a utility-first CSS framework that lets you style elements directly in your HTML using small, single-purpose classes like bg-black, rounded-full, and shadow-lg.

Why Tailwind? Well, traditional CSS requires you to write separate stylesheets and invent class names. Tailwind eliminates this overhead by providing pre-built utility classes. This is especially useful for an embeddable widget because all the styles are self-contained and won't conflict with the host website's CSS.

Create the file tailwind.config.js in your project root:

tail/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./public/**/*.{html,js}'],
  darkMode: 'class',
  theme: { extend: {} },
  plugins: []
};

This configuration tells Tailwind to scan all HTML and JavaScript files in the public folder for class names. The darkMode: 'class' setting enables dark mode toggling by adding a dark class to the widget container.

Create the source CSS file at src/input.css:

@tailwind base;
@tailwind components;src/input.css;
@tailwind utilities;

This file imports Tailwind's base styles, component classes, and utility classes. When you build, Tailwind will scan your code and generate a minimal CSS file containing only the classes you actually use.

Update your package.json with build scripts:

{
    "name": "ai-chatbot-widget",
    "version": "1.0.0",
    "private": true,
    "scripts": {
        "build:css": "npx tailwindcss -i ./src/input.css -o ./public/styles.css --minify",
        "deploy": "npm run build:css && wrangler deploy",
        "dev": "npm run build:css && wrangler dev"
    },
    "devDependencies": {
        "autoprefixer": "^10.4.23",
        "postcss": "^8.5.6",
        "tailwindcss": "^3.4.19",
        "wrangler": "^4.56.0"
    }
}

The build:css script compiles and minifies your Tailwind CSS. The deploy and dev scripts automatically build the CSS before starting the development server or deploying.

With styling ready to go, let's build the widget that users will actually interact with.

How to Build the Frontend Widget

The frontend widget is a self-contained JavaScript file that creates the entire chat interface. When someone adds your script to their website, it automatically creates the chat bubble button, the chat window, and handles all the interactive functionality.

Create the file public/widget.js:

/**
 * AI Chatbot Widget - Embeddable Script
 * Usage: <script src="https://your-domain.com/widget.js"></script>
 */
(function () {
  'use strict';
  const C = {
    u: window.CHATBOT_BASE_URL || '',
    t: window.CHATBOT_TITLE || 'AI Assistant',
    p: window.CHATBOT_PLACEHOLDER || 'Message...',
    g: window.CHATBOT_GREETING || '👋 Hi! How can I help you today?'
  };
  let open = 0, msgs = [], typing = 0, menu = 0;
  let dark = matchMedia('(prefers-color-scheme:dark)').matches;
  const $ = id => document.getElementById(id);
  const tog = (e, c, on) => e.classList.toggle(c, on);
  function init() {
    const l = document.createElement('link');
    l.rel = 'stylesheet';
    l.href = C.u + '/styles.css';
    document.head.appendChild(l);
    const d = document.createElement('div');
    d.id = 'cb';
    d.innerHTML = `
      <button id="cb-btn" class="fixed bottom-6 right-6 w-14 h-14 bg-black rounded-full shadow-2xl flex items-center justify-center cursor-pointer hover:scale-110 transition-all z-[99999]">
        <svg id="cb-o" class="w-6 h-6 text-white" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
          <path d="M21 11.5a8.38 8.38 0 01-.9 3.8 8.5 8.5 0 01-7.6 4.7 8.38 8.38 0 01-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 01-.9-3.8 8.5 8.5 0 014.7-7.6 8.38 8.38 0 013.8-.9h.5a8.48 8.48 0 018 8v.5z"/>
        </svg>
        <svg id="cb-x" class="w-6 h-6 text-white absolute opacity-0 scale-50 transition-all" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
          <path d="M6 18L18 6M6 6l12 12"/>
        </svg>
      </button>
      <div id="cb-w" class="fixed bottom-24 right-6 w-[400px] h-[600px] rounded-2xl shadow-2xl flex flex-col overflow-hidden z-[99999] opacity-0 scale-95 pointer-events-none transition-all origin-bottom-right bg-white dark:bg-gray-900">
        <!-- Header -->
        <div class="flex items-center justify-between px-5 py-4 border-b bg-white dark:bg-gray-900 border-gray-100 dark:border-gray-800">
          <div class="flex items-center gap-3">
            <div class="w-10 h-10 bg-black rounded-full flex items-center justify-center">
              <span class="text-white font-bold text-lg">C</span>
            </div>
            <h3 class="font-semibold text-gray-900 dark:text-white">${C.t}</h3>
          </div>
          <div class="relative">
            <button id="cb-m" class="p-2 hover:bg-gray-100 dark:hover:bg-gray-800 rounded-full">
              <svg class="w-5 h-5 text-gray-500" viewBox="0 0 24 24" fill="currentColor">
                <circle cx="12" cy="5" r="1.5"/><circle cx="12" cy="12" r="1.5"/><circle cx="12" cy="19" r="1.5"/>
              </svg>
            </button>
            <div id="cb-d" class="hidden absolute right-0 top-full mt-2 w-44 bg-white dark:bg-gray-800 rounded-xl shadow-xl border border-gray-100 dark:border-gray-700 py-1 z-50">
              <button id="cb-th" class="w-full px-4 py-2 text-left text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700 flex items-center gap-2">
                <svg id="cb-s" class="w-4 h-4 hidden" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="5"/></svg>
                <svg id="cb-n" class="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"/></svg>
                <span id="cb-tt">Dark Mode</span>
              </button>
              <button id="cb-cl" class="w-full px-4 py-2 text-left text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700 flex items-center gap-2">
                <svg class="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
                  <path d="M3 6h18M19 6v14a2 2 0 01-2 2H7a2 2 0 01-2-2V6m3 0V4a2 2 0 012-2h4a2 2 0 012 2v2"/>
                </svg>
                Clear Chat
              </button>
            </div>
          </div>
        </div>
        <!-- Messages -->
        <div id="cb-ms" class="flex-1 overflow-y-auto px-5 py-4 space-y-4 bg-gray-50 dark:bg-gray-950"></div>
        <!-- Typing Indicator -->
        <div id="cb-ty" class="hidden px-5 pb-2 bg-gray-50 dark:bg-gray-950">
          <div class="flex items-center gap-2 text-gray-400 text-sm">
            <div class="flex gap-1">
              <span class="w-2 h-2 bg-gray-400 rounded-full animate-bounce"></span>
              <span class="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style="animation-delay:.15s"></span>
              <span class="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style="animation-delay:.3s"></span>
            </div>
            Thinking...
          </div>
        </div>
        <!-- Input -->
        <form id="cb-f" class="flex items-center gap-3 px-4 py-4 border-t bg-white dark:bg-gray-900 border-gray-100 dark:border-gray-800">
          <input id="cb-i" type="text" class="flex-1 px-4 py-3 bg-gray-50 dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-full text-sm text-gray-900 dark:text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-gray-200 dark:focus:ring-gray-600" placeholder="${C.p}" autocomplete="off"/>
          <button type="submit" id="cb-se" class="p-3 hover:bg-gray-100 dark:hover:bg-gray-800 rounded-full disabled:opacity-50">
            <svg class="w-5 h-5 text-gray-600 dark:text-gray-300" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
              <path d="M22 2L11 13M22 2L15 22L11 13L2 9L22 2Z"/>
            </svg>
          </button>
        </form>
      </div>`;
    document.body.appendChild(d);
    bind();
    load();
    theme();
  }
  function bind() {
    $('cb-btn').onclick = flip;
    $('cb-f').onsubmit = send;
    $('cb-m').onclick = e => { e.stopPropagation(); menu = !menu; tog($('cb-d'), 'hidden', !menu); };
    $('cb-th').onclick = () => { dark = !dark; theme(); menu = 0; tog($('cb-d'), 'hidden', 1); };
    $('cb-cl').onclick = () => { msgs = []; draw(); menu = 0; tog($('cb-d'), 'hidden', 1); };
    document.onclick = () => menu && (menu = 0, tog($('cb-d'), 'hidden', 1));
  }
  function theme() {
    tog($('cb'), 'dark', dark);
    $('cb-tt').textContent = dark ? 'Light Mode' : 'Dark Mode';
    tog($('cb-s'), 'hidden', !dark);
    tog($('cb-n'), 'hidden', dark);
  }
  function flip() {
    open = !open;
    const w = $('cb-w'), o = $('cb-o'), x = $('cb-x');
    tog(w, 'opacity-0', !open);
    tog(w, 'scale-95', !open);
    tog(w, 'pointer-events-none', !open);
    tog(w, 'opacity-100', open);
    tog(w, 'scale-100', open);
    tog(o, 'opacity-0', open);
    tog(o, 'scale-50', open);
    tog(x, 'opacity-0', !open);
    tog(x, 'scale-50', !open);
    tog(x, 'opacity-100', open);
    tog(x, 'scale-100', open);
    if (open) {
      $('cb-i').focus();
      if (!msgs.length) add('assistant', C.g);
    }
  }
  function add(r, c) {
    msgs.push({ role: r, content: c });
    draw();
  }
  function esc(t) {
    const d = document.createElement('div');
    d.textContent = t;
    return d.innerHTML.replace(/\n/g, '<br>');
  }
  function draw() {
    $('cb-ms').innerHTML = msgs.map((m, i) => m.role === 'user'
      ? `<div class="flex justify-end">
          <div class="bg-black text-white rounded-2xl rounded-br-md px-4 py-3 max-w-[85%]">
            <div id="m${i}" class="text-sm whitespace-pre-wrap">${esc(m.content)}</div>
          </div>
        </div>`
      : `<div class="flex justify-start">
          <div class="bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 rounded-2xl rounded-bl-md px-4 py-3 max-w-[85%] border border-gray-200 dark:border-gray-700 shadow-sm">
            <div class="flex items-center gap-2 mb-2">
              <div class="w-6 h-6 bg-black rounded-full flex items-center justify-center">
                <span class="text-white font-bold text-xs">C</span>
              </div>
              <span class="text-sm font-medium text-gray-700 dark:text-gray-300">${C.t}</span>
            </div>
            <div id="m${i}" class="text-sm leading-relaxed whitespace-pre-wrap">${esc(m.content)}</div>
          </div>
        </div>`
    ).join('');
    $('cb-ms').scrollTop = $('cb-ms').scrollHeight;
  }
  async function send(e) {
    e.preventDefault();
    const m = $('cb-i').value.trim();
    if (!m || typing) return;
    add('user', m);
    $('cb-i').value = '';
    $('cb-se').disabled = 1;
    typing = 1;
    tog($('cb-ty'), 'hidden', 0);
    try {
      const r = await fetch(C.u + '/api/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ message: m }),
        credentials: 'include'
      });
      if (!r.ok) throw 0;
      const rd = r.body.getReader();
      const dc = new TextDecoder();
      let t = '', idx = null;
      while (1) {
        const { done, value } = await rd.read();
        if (done) break;
        for (const ln of dc.decode(value, { stream: 1 }).split('\n')) {
          if (!ln.startsWith('data: ')) continue;
          const d = ln.slice(6);
          if (d === '[DONE]') continue;
          try {
            const p = JSON.parse(d);
            if (p.response) {
              t += p.response;
              if (idx === null) {
                tog($('cb-ty'), 'hidden', 1);
                typing = 0;
                msgs.push({ role: 'assistant', content: t });
                idx = msgs.length - 1;
                draw();
              } else {
                msgs[idx].content = t;
                const el = $('m' + idx);
                if (el) el.innerHTML = esc(t);
              }
              $('cb-ms').scrollTop = $('cb-ms').scrollHeight;
            }
          } catch {}
        }
      }
    } catch {
      tog($('cb-ty'), 'hidden', 1);
      typing = 0;
      add('assistant', 'Sorry, an error occurred.');
    } finally {
      $('cb-se').disabled = 0;
      typing = 0;
      tog($('cb-ty'), 'hidden', 1);
    }
  }
  async function load() {
    try {
      const r = await fetch(C.u + '/api/history', { credentials: 'include' });
      if (r.ok) {
        const d = await r.json();
        if (d.messages?.length) {
          msgs = d.messages;
          draw();
        }
      }
    } catch {}
  }
  document.readyState === 'loading'
    ? document.addEventListener('DOMContentLoaded', init)
    : init();
})();

The widget uses an IIFE (Immediately Invoked Function Expression) to avoid polluting the global namespace. Here are the key functions:

• init(): Creates the widget HTML and injects it into the page

• bind(): Sets up all event listeners

• theme(): Toggles dark/light mode

• flip(): Opens and closes the chat window with animations

• draw(): Renders all messages

• send(): Handles message submission with streaming

• load(): Loads chat history from the server

The streaming handler in send() is particularly important. It reads the AI response chunk by chunk and updates the UI as each token arrives. Instead of re-rendering the entire message list on each token (which would cause visual flashing), it updates only the content of the current message element. This creates a smooth typing effect.

Now you need a simple page to test everything before deploying.

Create the Demo Page

The demo page serves as a testing ground during development and a showcase for your widget. When you or your users visit your deployed Worker URL directly, they will see this page with the chatbot widget already integrated.

Create public/index.html: This demo page will be for your internal testing.

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>AI Chatbot Widget Demo</title>
  <link rel="stylesheet" href="/styles.css">
</head>

<body class="min-h-screen bg-gradient-to-br from-indigo-500 to-purple-600 flex items-center justify-center p-8">
  <div class="text-center text-white">
    <h1 class="text-4xl font-bold mb-4">AI Chatbot Widget</h1>
  </div>
  <script>    window.CHATBOT_BASE_URL = ''; window.CHATBOT_TITLE = 'Support'; window.CHATBOT_GREETING = "👋 Hi! I'm here to help with your questions!";  </script>
  <script src="/widget.js"></script>
</body>

</html>

This minimal page displays a title and loads the chatbot widget. The CHATBOT_BASE_URL is set to an empty string because when served from the same Worker, relative URLs work automatically. This is the exact same code someone would use to embed the widget on their own website, just with their own base URL instead.

With all the code in place, you are ready to deploy your chatbot to Cloudflare.

How to Run it in Your Local System

Once all the files are added, run the command npm run dev to see how the chat widget looks in http://localhost:8787:

How to Deploy to Cloudflare

Deployment is a single command. Run:

npm run deploy

This command first builds your Tailwind CSS, then deploys everything to Cloudflare. After deployment completes, you will see a URL like https://ai-chatbot-widget.YOUR-SUBDOMAIN.workers.dev.

in my case URL is https://ai-chatbot-widget.mv.workers.dev/

How to Seed the FAQ Database

Before your chatbot can answer questions from your FAQ, you need to populate the Vectorize index. Run this command (replace the URL with your actual deployment URL):

curl -X POST https://ai-chatbot-widget.YOUR-SUBDOMAIN.workers.dev/api/seed

You should see this response:

{"success":true,"count":8}

This means eight FAQ entries have been converted to vectors and stored in Vectorize. Your chatbot is now live and ready to answer questions!

Visit your deployment URL to test it out. Try asking about shipping, returns, or payment methods. The chatbot will respond using the FAQ context you just seeded.

Your chatbot is now live and ready to answer questions. You can check the Cloudflare dashboard to view the deployment. (The screenshot below is from the Cloudflare dashboard.)

How to Embed the Widget on Any Website

Now for the exciting part: adding your chatbot to any website. All it takes is two script tags before the closing </body> tag:

<script>
  window.CHATBOT_BASE_URL = 'https://ai-chatbot-widget.YOUR-SUBDOMAIN.workers.dev';
  window.CHATBOT_TITLE = 'Your Company';
  window.CHATBOT_GREETING = '👋 How can I help you today?';
</script>
<script src="https://ai-chatbot-widget.YOUR-SUBDOMAIN.workers.dev/widget.js"></script>

Replace YOUR-SUBDOMAIN with your actual Cloudflare Workers subdomain.

Or you can also open your Cloudflare deployment URL for testing.

Configuration Options

You can customize the widget using these variables:

How to Customize Your Chatbot

Your chatbot is working, but you probably want to tailor it to your specific use case. Here are the most common customizations.

How to Add Your Own FAQs

Open src/index.js and find the seed function. Replace the sample FAQs with your own question-answer pairs:

const faqs = [
  ['Your question here?', 'Your answer here.'],
  ['Another question?', 'Another answer.']
  // Add more Q&A pairs
];

Then redeploy with npm run deploy and call the /api/seed endpoint again to update your vector database.

How to Change the AI Personality

Edit the SYS constant at the top of src/index.js:

const SYS = `You are a friendly assistant for [Your Company].
You help customers with [your main services].
Always be helpful and professional.`;

This system prompt shapes how the AI responds to users.

How to Style the Widget

All styles use Tailwind CSS classes in widget.js. To change the appearance:

• Colors: Change bg-black to your brand color

• Size: Adjust w-[400px] h-[600px] for the chat window dimensions

• Position: Modify bottom-6 right-6 for placement

Conclusion

Congratulations! You have built a complete AI chatbot widget that rivals expensive SaaS solutions like Intercom and Drift. Your chatbot streams AI responses in real-time, answers questions based on your FAQ using RAG, and remembers conversations across sessions—all for free.

Here is a quick recap of what you built:

• A backend Worker that handles chat, sessions, and FAQ search

• A frontend widget that can be embedded on any website

• Integration with Workers AI for intelligent responses

• Vectorize for semantic FAQ search

• KV for persistent conversation history

The Cloudflare stack offers generous free tiers that should cover most use cases:

• Workers: 100,000 requests per day

• Workers AI: 10,000 neurons per day

• Vectorize: 5 million vector operations per month

• KV: 100,000 reads and 1,000 writes per day

For most websites, you can run this chatbot completely free.

The source code for this project is available on GitHub.

In this tutorial, you will build a Tic-Tac-Toe AI that learns optimal strategies through Q-learning, a foundational RL algorithm. You will implement adaptive difficulty levels, visualize the learning process in real-time, and explore advanced optimization techniques.

By the end of this tutorial, you’ll have a production-ready web application that demonstrates practical RL concepts – all running directly in the browser with vanilla JavaScript.

What You’ll Learn

In this tutorial, you’ll learn:

• Core reinforcement learning concepts including Q-learning, exploration vs exploitation, and reward shaping.

• How to implement a complete Q-learning algorithm with state management.

• Advanced techniques like epsilon decay and experience replay.

• How to build an interactive game with HTML5 Canvas and responsive controls.

• Performance optimization for real-time AI decision-making.

• Visualization techniques to understand the AI's learning process.

Prerequisites

To get the most out of this tutorial, you should have:

• Solid understanding of JavaScript (ES6+ syntax, classes, array methods).

• Familiarity with HTML5 Canvas API for graphics rendering.

• Basic knowledge of algorithms and data structures.

• Understanding of asynchronous JavaScript (Promises, async/await).

You don’t need any prior machine learning experience, as I’ll explain all RL concepts from scratch.

Table of Contents

• Why Use Reinforcement Learning for Game AI?

• How to Understand Q-Learning: The Foundation

• Project Architecture Overview

• How to Build the HTML Interface with Tailwind CSS

• How to Implement the Q-Learning Algorithm

• How to Understand the Enhanced Features

• How to Test Your Implementation

• Advanced Optimizations and Extensions

• Common Pitfalls and Solutions

• How to Extend This to Other Games

• Conclusion

Why Use Reinforcement Learning for Game AI?

Games provide an ideal environment for learning RL because they have:

1. Clear state representations – The game board at any moment

2. Discrete action spaces – A finite set of valid moves

3. Immediate feedback – Win, lose, or draw outcomes

4. Deterministic rules – Consistent behavior across games

Traditional game AI uses techniques like minimax with alpha-beta pruning. While effective, these approaches require you to explicitly program game strategies. RL agents, by contrast, discover optimal strategies through experience – much like humans learn through practice.

Tic-Tac-Toe serves as an excellent starting point because:

• The state space is manageable (5,478 unique positions)

• Games are short, allowing rapid iteration

• Perfect play is achievable, providing a clear success metric

• The concepts scale to more complex games

How to Understand Q-Learning: The Foundation

Q-learning is a model-free, value-based RL algorithm. Let me break down what that means:

• Model-free means that the agent doesn’t need to understand the game's rules. It learns purely from experience.

• Value-based means that the agent learns the "value" of each action in each state, then chooses the action with the highest value.

Core Components

There are a few key components you’ll need to understand before building this game.

First, we have state (s), which here is the current game board configuration. We represent this as a 9-character string (for example, "XO-X-----" where - represents empty cells).

Next, we have action (a), which is a move the AI can make. We represent this as an index from 0-8 corresponding to board positions.

Then there’s reward (r), the numerical feedback from the environment:

• +1 for winning

• -1 for losing

• 0 for draws or ongoing games

We also have Q-Table, a lookup table storing Q(s,a) – the expected cumulative reward for taking action a in state s.

And finally, there’s policy, the strategy for choosing actions. We use an epsilon-greedy policy that balances exploration and exploitation.

The Q-Learning Update Rule

The heart of Q-learning is this update formula:

Q(s,a) ← Q(s,a) + α[r + γ max Q(s',a') - Q(s,a)]

Where:

• α (alpha) = Learning rate (0 to 1) – how much to update the Q-value

• γ (gamma) = Discount factor (0 to 1) – how much to value future rewards

• s' = Next state after taking action a

• max Q(s',a') = Highest Q-value available in the next state.

This formula implements temporal difference learning. This means it updates our estimate of Q(s,a) based on the difference between our current estimate and a better estimate using the actual reward received plus the best possible future reward.

How Exploration vs Exploitation Works

A critical challenge in reinforcement learning is the "exploration vs. exploitation" trade-off. To understand why this is difficult, imagine choosing a place for dinner.

• Exploitation: You could go to your favorite restaurant. You know the food is good, and you're almost guaranteed a satisfying meal. This is a safe, reliable choice that maximizes your immediate reward based on past experience.

• Exploration: You could try a new, unknown restaurant. It might be a disaster, or you might discover a new favorite that’s even better than your old one. This is a risky choice that provides no immediate guarantee, but it's the only way to gather new information and potentially find a better long-term strategy.

The same dilemma applies to our AI. If it only exploits its current knowledge, it might get stuck using a mediocre strategy, never discovering the brilliant moves that lead to a guaranteed win. If it only explores by making random moves, it will never learn to use the good strategies it finds and will play poorly.

The key is to balance the two: explore enough to find optimal strategies, but exploit that knowledge to win games.

To achieve this balance, we use an epsilon-greedy (ϵ) strategy. It’s a simple but powerful way to manage this trade-off:

1. We choose a small value for epsilon (ϵ), for example, 0.1 (which represents a 10% probability).

2. Before the AI makes a move, it generates a random number between 0 and 1.

3. If the random number is less than ϵ (the 10% chance): The AI ignores its strategy and chooses a random available move. This is exploration.

4. If the random number is greater than or equal to ϵ (the 90% chance): The AI chooses the best-known move from its Q-table.This is exploitation.

This ensures the AI primarily plays to win but still dedicates a small fraction of its moves to trying new things. We will also implement epsilon decay – starting with a higher ϵ value to encourage exploration when the AI is inexperienced, and gradually lowering it as the AI learns and becomes more confident in its strategy.

Project Architecture Overview

Before you start coding, here's the structure of the application you’ll build:

tic-tac-toe-ai/
├── index.html          # Game interface with Tailwind CSS
└── game.js            # Complete game logic and AI

You will organize your code into two main classes in game.js:

1. QLearning: Implements the Q-learning algorithm.

2. TicTacToe: Manages game state and rendering.

How to Build the HTML Interface with Tailwind CSS

Create an index.html file with Tailwind CSS CDN:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Tic-Tac-Toe AI with Q-Learning</title>
  <script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="bg-gradient-to-br from-purple-600 to-purple-900 min-h-screen flex items-center justify-center p-4">

  <div class="bg-white rounded-3xl shadow-2xl p-8 max-w-5xl w-full">
    <!-- Header -->
    <div class="text-center mb-8">
      <h1 class="text-4xl font-bold text-gray-800 mb-2">🎮 Tic-Tac-Toe AI</h1>
      <p class="text-gray-600 text-lg">Watch the AI learn through reinforcement learning</p>
    </div>

    <!-- Training Indicator -->
    <div id="trainingIndicator" class="hidden bg-yellow-100 border-l-4 border-yellow-500 text-yellow-700 p-4 mb-6 rounded">
      <p class="font-semibold">🤖 AI is training... <span id="trainingProgress"></span></p>
    </div>

    <!-- Main Game Area -->
    <div class="grid md:grid-cols-2 gap-8">

      <!-- Canvas Section -->
      <div class="flex flex-col items-center">
        <canvas id="gameCanvas" width="400" height="400" 
                class="border-4 border-purple-500 rounded-xl shadow-lg cursor-pointer hover:scale-[1.02] transition-transform">
        </canvas>
        <div id="gameStatus" class="mt-4 text-xl font-bold text-gray-700 min-h-[30px]">
          Your turn! (X)
        </div>
      </div>

      <!-- Controls Section -->
      <div class="space-y-6">

        <!-- Game Controls -->
        <div class="bg-gray-50 rounded-xl p-6">
          <h3 class="text-xl font-bold text-gray-800 mb-4">Game Controls</h3>
          <div class="space-y-3">
            <button onclick="game.reset()" 
                    class="w-full bg-purple-600 hover:bg-purple-700 text-white font-semibold py-3 px-6 rounded-lg transition-all hover:-translate-y-0.5 shadow-md hover:shadow-lg">
              New Game
            </button>
            <button onclick="game.startTraining()" 
                    class="w-full bg-green-600 hover:bg-green-700 text-white font-semibold py-3 px-6 rounded-lg transition-all hover:-translate-y-0.5 shadow-md hover:shadow-lg">
              Train AI (1000 games)
            </button>
            <button onclick="game.resetAI()" 
                    class="w-full bg-red-600 hover:bg-red-700 text-white font-semibold py-3 px-6 rounded-lg transition-all hover:-translate-y-0.5 shadow-md hover:shadow-lg">
              Reset AI Memory
            </button>
          </div>
        </div>

        <!-- Difficulty Selector -->
        <div class="bg-gray-50 rounded-xl p-6">
          <h3 class="text-xl font-bold text-gray-800 mb-4">Difficulty Level</h3>
          <div class="grid grid-cols-3 gap-2">
            <button onclick="game.setDifficulty('beginner')" id="diffBeginner"
                    class="py-2 px-4 rounded-lg font-semibold text-sm transition-all bg-green-100 text-green-700 hover:bg-green-200">
              🌱 Beginner
            </button>
            <button onclick="game.setDifficulty('intermediate')" id="diffIntermediate"
                    class="py-2 px-4 rounded-lg font-semibold text-sm transition-all bg-white text-gray-700 hover:bg-gray-100 border-2 border-purple-500">
              🎯 Medium
            </button>
            <button onclick="game.setDifficulty('expert')" id="diffExpert"
                    class="py-2 px-4 rounded-lg font-semibold text-sm transition-all bg-white text-gray-700 hover:bg-gray-100">
              🔥 Expert
            </button>
          </div>
        </div>

        <!-- AI Parameters -->
        <div class="bg-gray-50 rounded-xl p-6">
          <h3 class="text-xl font-bold text-gray-800 mb-4">AI Parameters</h3>

          <div class="space-y-4">
            <!-- Learning Rate -->
            <div>
              <div class="flex justify-between items-center mb-2">
                <label class="text-sm font-medium text-gray-700 flex items-center gap-1">
                  Learning Rate (α)
                  <span class="group relative">
                    <span class="cursor-help text-purple-500">ⓘ</span>
                    <span class="invisible group-hover:visible absolute left-0 top-6 w-64 bg-gray-900 text-white text-xs rounded-lg p-3 z-10 shadow-xl">
                      Controls how quickly the AI updates its knowledge. Higher values = faster learning but less stability. Recommended: 0.1-0.3
                    </span>
                  </span>
                </label>
                <span id="learningRateValue" class="text-sm font-bold text-purple-600">0.1</span>
              </div>
              <input type="range" id="learningRate" min="0.01" max="0.5" step="0.01" value="0.1"
                     class="w-full h-2 bg-gray-200 rounded-lg appearance-none cursor-pointer">
            </div>

            <!-- Discount Factor -->
            <div>
              <div class="flex justify-between items-center mb-2">
                <label class="text-sm font-medium text-gray-700 flex items-center gap-1">
                  Discount Factor (γ)
                  <span class="group relative">
                    <span class="cursor-help text-purple-500">ⓘ</span>
                    <span class="invisible group-hover:visible absolute left-0 top-6 w-64 bg-gray-900 text-white text-xs rounded-lg p-3 z-10 shadow-xl">
                      Determines how much the AI values future rewards vs immediate rewards. Higher = more long-term thinking. Recommended: 0.85-0.95
                    </span>
                  </span>
                </label>
                <span id="discountFactorValue" class="text-sm font-bold text-purple-600">0.9</span>
              </div>
              <input type="range" id="discountFactor" min="0.5" max="0.99" step="0.01" value="0.9"
                     class="w-full h-2 bg-gray-200 rounded-lg appearance-none cursor-pointer">
            </div>

            <!-- Exploration Rate -->
            <div>
              <div class="flex justify-between items-center mb-2">
                <label class="text-sm font-medium text-gray-700 flex items-center gap-1">
                  Exploration Rate (ε)
                  <span class="group relative">
                    <span class="cursor-help text-purple-500">ⓘ</span>
                    <span class="invisible group-hover:visible absolute left-0 top-6 w-64 bg-gray-900 text-white text-xs rounded-lg p-3 z-10 shadow-xl">
                      Chance the AI tries random moves vs using learned strategy. Higher = more experimentation. Set to 0.01 for best play after training.
                    </span>
                  </span>
                </label>
                <span id="explorationRateValue" class="text-sm font-bold text-purple-600">0.1</span>
              </div>
              <input type="range" id="explorationRate" min="0" max="0.5" step="0.01" value="0.1"
                     class="w-full h-2 bg-gray-200 rounded-lg appearance-none cursor-pointer">
            </div>
          </div>
        </div>

        <!-- Statistics -->
        <div class="bg-gray-50 rounded-xl p-6">
          <h3 class="text-xl font-bold text-gray-800 mb-4">Statistics</h3>
          <div class="grid grid-cols-3 gap-3">
            <div class="bg-white rounded-lg p-3 text-center shadow-sm">
              <div class="text-xs text-gray-600 mb-1">Games</div>
              <div id="gamesPlayed" class="text-2xl font-bold text-gray-800">0</div>
            </div>
            <div class="bg-white rounded-lg p-3 text-center shadow-sm">
              <div class="text-xs text-gray-600 mb-1">AI Wins</div>
              <div id="aiWins" class="text-2xl font-bold text-green-600">0</div>
            </div>
            <div class="bg-white rounded-lg p-3 text-center shadow-sm">
              <div class="text-xs text-gray-600 mb-1">You Win</div>
              <div id="playerWins" class="text-2xl font-bold text-red-600">0</div>
            </div>
            <div class="bg-white rounded-lg p-3 text-center shadow-sm">
              <div class="text-xs text-gray-600 mb-1">Draws</div>
              <div id="draws" class="text-2xl font-bold text-gray-600">0</div>
            </div>
            <div class="bg-white rounded-lg p-3 text-center shadow-sm">
              <div class="text-xs text-gray-600 mb-1">States</div>
              <div id="statesLearned" class="text-2xl font-bold text-purple-600">0</div>
            </div>
            <div class="bg-white rounded-lg p-3 text-center shadow-sm">
              <div class="text-xs text-gray-600 mb-1">Win Rate</div>
              <div id="winRate" class="text-2xl font-bold text-blue-600">0%</div>
            </div>
          </div>
        </div>

      </div>
    </div>
  </div>

  <script src="game.js"></script>
</body>
</html>

This HTML structure creates a responsive, modern interface using Tailwind CSS utility classes. The layout uses a two-column grid on medium screens and larger, with the game canvas on the left and all controls on the right. The training indicator starts hidden and only appears during AI training sessions.

All interactive elements (buttons, sliders) use onclick handlers and oninput events to communicate with the JavaScript game logic. The tooltip system uses CSS group hover states to show explanatory text when users hover over the info icons, helping them understand each parameter without cluttering the interface.

Let’s talk in a bit more detail about some key parts of the code:

• Header Section: Displays the game title and subtitle to introduce users to the application.

• Training Indicator: A yellow banner that appears only during AI training sessions, showing progress updates every 50 games. This provides visual feedback so users know the training is in progress.

• Canvas Section: Contains the HTML5 Canvas element where the game board is drawn. The canvas is 400x400 pixels and styled with Tailwind classes for borders and hover effects. Below it is a status message that updates based on game state.

• Game Controls: Three primary buttons that let users start a new game, train the AI through 1000 self-play games, or completely reset the AI's memory (clearing the Q-table).

• Difficulty Selector: Three buttons for choosing AI difficulty. Beginner mode makes the AI play randomly 70% of the time, Intermediate uses Q-learning, and Expert implements perfect minimax play.

• AI Parameters: Three range sliders with tooltips that let users adjust the core reinforcement learning hyperparameters in real-time. The tooltips appear on hover and explain what each parameter does.

• Statistics Panel: A grid of six cards displaying real-time metrics including games played, wins/losses/draws, learned states, and AI win rate percentage.

All interactive elements use onclick handlers that call methods from the game object defined in game.js.

How to Implement the Q-Learning Algorithm

Now, let's bring the theory to life. Create a game.js file. We will build this file step-by-step, but if you get stuck at any point or want to see the complete code for reference, you can find the final version on GitHub here.

Our code will be structured into two main classes: QLearning, which will handle the AI's "brain" and learning logic, and TicTacToe, which will manage the game state, rendering, and user interaction.

The QLearning Class: The AI's Brain

This class will contain all the logic for the reinforcement learning agent. Let's build it piece by piece.

1. Constructor and Q-Table Management

First, let's set up the constructor and a method to access our Q-table. The Q-table will be a JavaScript Map, which is highly efficient for storing and retrieving key-value pairs where the key (the board state) is a string.

// In game.js

// Q-Learning Agent with localStorage support
class QLearning {
  constructor(lr = 0.1, gamma = 0.9, epsilon = 0.1) {
    this.q = new Map(); // Stores Q-values: { state => [q_action_0, q_action_1, ...] }
    this.lr = lr; // Learning Rate (α)
    this.gamma = gamma; // Discount Factor (γ)
    this.epsilon = epsilon; // Exploration Rate (ε)
    this.difficulty = 'intermediate';
  }

  getQ(state) {
    if (!this.q.has(state)) {
      this.q.set(state, Array(9).fill(0));
    }
    return this.q.get(state);
  }

• The constructor initializes our three key hyperparameters (α, γ, ϵ) and the Q-table itself.

• getQ(state) is a crucial helper function. It safely retrieves the array of Q-values for a given board state. If the AI has never seen this state before, it creates a new entry in the map with an array of nine zeros, representing an initial Q-value of 0 for each possible move.

2. Choosing an Action (The Epsilon-Greedy Strategy)

Next, we'll implement the getAction method. This is where the AI decides which move to make, incorporating our difficulty levels and the epsilon-greedy strategy.

  getAction(state, available) {
    // Difficulty-based behavior
    if (this.difficulty === 'beginner') {
      // 70% random moves for beginner
      if (Math.random() < 0.7) {
        return available[~~(Math.random() * available.length)];
      }
    } else if (this.difficulty === 'expert') {
      // Use minimax for perfect play
      return this.getMinimaxAction(state, available);
    }

    // Intermediate: epsilon-greedy
    if (Math.random() < this.epsilon) {
      return available[~~(Math.random() * available.length)];
    }
    const q = this.getQ(state);
    return available.reduce((best, a) => q[a] > q[best] ? a : best, available[0]);
  }

• The logic first checks the difficulty. 'Beginner' is mostly random, while 'Expert' defers to a separate, perfect-play algorithm.

• For the 'Intermediate' level, it implements the epsilon-greedy logic. With probability ϵ, it explores (chooses a random move). Otherwise, it exploits (chooses the best-known move from the Q-table).

3. The Learning Rule

The update method is the heart of the algorithm. It's the direct implementation of the Q-learning formula we discussed earlier.

Q(s, a) ← Q(s, a) + α [r + γ max(a') Q(s', a') − Q(s, a)]

  update(s, a, r, s2, available2) {
    const q = this.getQ(s);
    const maxQ2 = available2.length ? Math.max(...available2.map(a_prime => this.getQ(s2)[a_prime])) : 0;
    q[a] += this.lr * (r + this.gamma * maxQ2 - q[a]);
  }

• maxQ2 calculates the max Q(s',a') part of the formula – the best possible Q-value the AI can get from its next move.

• The final line is a direct translation of the formula, updating the value of the action just taken based on the reward and future potential.

4. Minimax for Expert Mode

For our 'Expert' level, we'll implement the minimax algorithm, a classic recursive algorithm from game theory that guarantees perfect play.

  getMinimaxAction(state, available) {
    let bestScore = -Infinity;
    let bestMove = available[0];

    for (const move of available) {
      const newState = state.substring(0, move) + 'O' + state.substring(move + 1);
      const score = this.minimax(newState, 0, false);
      if (score > bestScore) {
        bestScore = score;
        bestMove = move;
      }
    }
    return bestMove;
  }

  minimax(state, depth, isMaximizing) {
    const winner = this.checkWinnerStatic(state);
    if (winner === 'O') return 10 - depth;
    if (winner === 'X') return depth - 10;
    if (winner === 'draw') return 0;

    const available = [...state].map((c, i) => c === '-' ? i : null).filter(x => x !== null);

    if (isMaximizing) {
      let best = -Infinity;
      for (const move of available) {
        const newState = state.substring(0, move) + 'O' + state.substring(move + 1);
        best = Math.max(best, this.minimax(newState, depth + 1, false));
      }
      return best;
    } else {
      let best = Infinity;
      for (const move of available) {
        const newState = state.substring(0, move) + 'X' + state.substring(move + 1);
        best = Math.min(best, this.minimax(newState, depth + 1, true));
      }
      return best;
    }
  }

  checkWinnerStatic(state) {
    const patterns = [[0,1,2],[3,4,5],[6,7,8],[0,3,6],[1,4,7],[2,5,8],[0,4,8],[2,4,6]];
    for (const p of patterns) {
      if (state[p[0]] !== '-' && state[p[0]] === state[p[1]] && state[p[1]] === state[p[2]]) {
        return state[p[0]];
      }
    }
    return state.includes('-') ? null : 'draw';
  }

5. Helper and Persistence Methods

Finally, let's add methods for epsilon decay, resetting the AI's memory, and saving/loading the Q-table to localStorage.

  decay() {
    this.epsilon = Math.max(0.01, this.epsilon * 0.995);
  }

  reset() {
    this.q.clear();
    this.epsilon = 0.1;
  }

  save() {
    const data = {
      q: Array.from(this.q.entries()),
      lr: this.lr,
      gamma: this.gamma,
      epsilon: this.epsilon,
      difficulty: this.difficulty
    };
    localStorage.setItem('tictactoe_ai', JSON.stringify(data));
  }

  load() {
    const saved = localStorage.getItem('tictactoe_ai');
    if (!saved) return false;

    try {
      const data = JSON.parse(saved);
      this.q = new Map(data.q);
      this.lr = data.lr;
      this.gamma = data.gamma;
      this.epsilon = data.epsilon;
      this.difficulty = data.difficulty || 'intermediate';
      return true;
    } catch (e) {
      console.error('Failed to load AI state:', e);
      return false;
    }
  }

  clearStorage() {
    localStorage.removeItem('tictactoe_ai');
  }
}

The TicTacToe Class: Managing the Game

Now that we have our AI "brain," we need to build the game around it. This class will handle rendering the board, processing user clicks, managing game flow, and calling the AI when it's its turn.

1. Constructor and Control Initialization

The constructor sets up the game's initial state, gets a reference to the HTML canvas, and wires up event listeners for user input.

class TicTacToe {
  constructor() {
    this.board = '---------';
    this.ai = new QLearning();
    this.stats = { played: 0, aiWins: 0, playerWins: 0, draws: 0 };
    this.training = false;
    this.gameOver = false;

    this.canvas = document.getElementById('gameCanvas');
    this.ctx = this.canvas.getContext('2d');
    this.cellSize = 133.33;

    this.canvas.onclick = e => this.handleClick(e);
    this.initControls();
    this.loadState();
    this.draw();
  }

  initControls() {
    ['learningRate', 'discountFactor', 'explorationRate'].forEach(id => {
      const el = document.getElementById(id);
      el.oninput = e => {
        const val = parseFloat(e.target.value);
        document.getElementById(id + 'Value').textContent = val.toFixed(2);
        if (id === 'learningRate') this.ai.lr = val;
        if (id === 'discountFactor') this.ai.gamma = val;
        if (id === 'explorationRate') this.ai.epsilon = val;
        this.saveState();
      };
    });
  }

initControls connects our HTML sliders to the AI's parameters, allowing for real-time adjustments.

2. Difficulty and UI Methods

These methods manage the difficulty setting and update the UI accordingly.

  setDifficulty(level) {
    this.ai.difficulty = level;

    // Update button styles
    ['beginner', 'intermediate', 'expert'].forEach(diff => {
      const btn = document.getElementById(`diff${diff.charAt(0).toUpperCase() + diff.slice(1)}`);
      if (diff === level) {
        btn.className = 'py-2 px-4 rounded-lg font-semibold text-sm transition-all bg-purple-600 text-white border-2 border-purple-600';
      } else {
        btn.className = 'py-2 px-4 rounded-lg font-semibold text-sm transition-all bg-white text-gray-700 hover:bg-gray-100';
      }
    });

    if (level === 'beginner') this.setStatus('🌱 Beginner mode: AI makes more mistakes');
    else if (level === 'intermediate') this.setStatus('🎯 Medium mode: Balanced AI using Q-learning');
    else this.setStatus('🔥 Expert mode: Perfect AI using minimax algorithm');

    this.saveState();
  }

3. Drawing and Rendering

These methods use the HTML5 Canvas API to visually represent the game state.

  draw() {
    const { ctx, canvas, cellSize } = this;
    ctx.fillStyle = '#fff';
    ctx.fillRect(0, 0, canvas.width, canvas.height);

    ctx.strokeStyle = '#8b5cf6';
    ctx.lineWidth = 4;
    for (let i = 1; i < 3; i++) {
      ctx.beginPath();
      ctx.moveTo(i * cellSize, 0);
      ctx.lineTo(i * cellSize, canvas.height);
      ctx.stroke();
      ctx.beginPath();
      ctx.moveTo(0, i * cellSize);
      ctx.lineTo(canvas.width, i * cellSize);
      ctx.stroke();
    }

    for (let i = 0; i < 9; i++) {
      const symbol = this.board[i];
      if (symbol === '-') continue;

      const x = (i % 3) * cellSize + cellSize / 2;
      const y = ~~(i / 3) * cellSize + cellSize / 2;

      ctx.strokeStyle = symbol === 'X' ? '#ef4444' : '#10b981';
      ctx.lineWidth = 8;
      ctx.lineCap = 'round';

      if (symbol === 'X') {
        const s = cellSize * 0.3;
        ctx.beginPath();
        ctx.moveTo(x - s, y - s);
        ctx.lineTo(x + s, y + s);
        ctx.stroke();
        ctx.beginPath();
        ctx.moveTo(x + s, y - s);
        ctx.lineTo(x - s, y + s);
        ctx.stroke();
      } else {
        ctx.beginPath();
        ctx.arc(x, y, cellSize * 0.3, 0, Math.PI * 2);
        ctx.stroke();
      }
    }

    const winner = this.checkWinner();
    if (winner?.line) this.drawWinLine(winner.line);
  }

  drawWinLine(line) {
    const [a, , c] = line;
    const startX = (a % 3) * this.cellSize + this.cellSize / 2;
    const startY = ~~(a / 3) * this.cellSize + this.cellSize / 2;
    const endX = (c % 3) * this.cellSize + this.cellSize / 2;
    const endY = ~~(c / 3) * this.cellSize + this.cellSize / 2;

    this.ctx.strokeStyle = '#fbbf24';
    this.ctx.lineWidth = 6;
    this.ctx.beginPath();
    this.ctx.moveTo(startX, startY);
    this.ctx.lineTo(endX, endY);
    this.ctx.stroke();
  }

4. Player Interaction and the Game Loop

This is the core interactive logic. handleClick translates a click into a board position, move updates the state, and aiMove gets an action from the QLearning class and executes it.

  handleClick(e) {
    if (this.gameOver || this.training) return;

    const rect = this.canvas.getBoundingClientRect();
    const col = ~~((e.clientX - rect.left) / this.cellSize);
    const row = ~~((e.clientY - rect.top) / this.cellSize);
    const idx = row * 3 + col;

    if (this.board[idx] === '-') {
      this.move(idx, 'X');
      if (!this.gameOver) setTimeout(() => this.aiMove(), 300);
    }
  }

  move(idx, player) {
    if (this.board[idx] !== '-' || this.gameOver) return false;
    this.board = this.board.substring(0, idx) + player + this.board.substring(idx + 1);
    this.draw();
    this.checkGameOver();
    return true;
  }

  aiMove() {
    if (this.gameOver) return;

    const state = this.board;
    const available = this.getAvailable();
    const action = this.ai.getAction(state, available);

    this.move(action, 'O');

    const winner = this.checkWinner();
    const reward = winner?.winner === 'O' ? 1 : winner?.winner === 'X' ? -1 : 0;
    this.ai.update(state, action, reward, this.board, this.getAvailable());
  }

After the AI moves, it immediately calls this.ai.update() to learn from the result of its action.

5. The Rules Engine

These helpers determine the game's state: available moves, winner, and game over conditions.

  getAvailable() {
    return [...this.board].map((c, i) => c === '-' ? i : null).filter(x => x !== null);
  }

  checkWinner() {
    const patterns = [[0,1,2],[3,4,5],[6,7,8],[0,3,6],[1,4,7],[2,5,8],[0,4,8],[2,4,6]];
    for (const p of patterns) {
      if (this.board[p[0]] !== '-' && 
          this.board[p[0]] === this.board[p[1]] && 
          this.board[p[1]] === this.board[p[2]]) {
        return { winner: this.board[p[0]], line: p };
      }
    }
    return this.board.includes('-') ? null : { winner: 'draw', line: null };
  }

  checkGameOver() {
    const result = this.checkWinner();
    if (!result) return;

    this.gameOver = true;
    this.stats.played++;

    if (result.winner === 'X') {
      this.stats.playerWins++;
      if (!this.training) this.setStatus('🎉 You win!');
    } else if (result.winner === 'O') {
      this.stats.aiWins++;
      if (!this.training) this.setStatus('🤖 AI wins!');
    } else {
      this.stats.draws++;
      if (!this.training) this.setStatus('🤝 Draw!');
    }

    if (!this.training) {
      this.updateStats();
      this.saveState();
    }
  }

6. UI and Statistics Updates

These methods connect the internal game state to the HTML elements, displaying status messages and statistics.

  setStatus(msg) {
    document.getElementById('gameStatus').textContent = msg;
  }

  updateStats() {
    document.getElementById('gamesPlayed').textContent = this.stats.played;
    document.getElementById('aiWins').textContent = this.stats.aiWins;
    document.getElementById('playerWins').textContent = this.stats.playerWins;
    document.getElementById('draws').textContent = this.stats.draws;
    document.getElementById('statesLearned').textContent = this.ai.q.size;

    const winRate = this.stats.played ? (this.stats.aiWins / this.stats.played * 100).toFixed(1) : 0;
    document.getElementById('winRate').textContent = `${winRate}%`;
  }

7. Game and AI Management

These methods are wired to the control buttons for resetting the game or the AI's memory.

  reset() {
    this.board = '---------';
    this.gameOver = false;
    this.draw();
    this.setStatus('Your turn! (X)');
  }

  resetAI() {
    if (confirm('Reset AI memory? All progress will be lost.')) {
      this.ai.reset();
      this.ai.clearStorage();
      this.stats = { played: 0, aiWins: 0, playerWins: 0, draws: 0 };
      this.updateStats();
      this.reset();
      this.setStatus('AI memory reset!');
      localStorage.removeItem('tictactoe_stats');
    }
  }

8. The Self-Play Training Loop

This is the logic for the "Train AI" button, allowing the AI to learn rapidly by playing against itself.

  async startTraining() {
    this.training = true;
    document.getElementById('trainingIndicator').classList.remove('hidden');

    const originalEpsilon = this.ai.epsilon;
    this.ai.epsilon = 0.3; // Higher exploration during training

    for (let i = 0; i < 1000; i++) {
      await this.trainGame();
      this.ai.decay();
      if (i % 50 === 0) {
        document.getElementById('trainingProgress').textContent = `${i + 1}/1000`;
        await new Promise(r => setTimeout(r, 0)); // Allow UI to update
      }
    }

    this.ai.epsilon = originalEpsilon;
    this.training = false;
    document.getElementById('trainingIndicator').classList.add('hidden');
    this.updateStats();
    this.reset();
    this.setStatus('Training complete!');
    this.saveState();
  }

  async trainGame() {
    this.board = '---------';
    this.gameOver = false;
    const moves = [];

    while (!this.gameOver && this.getAvailable().length > 0) {
      const state = this.board;
      const available = this.getAvailable();
      // Alternate players (X and O) are both the AI
      const player = moves.length % 2 === 0 ? 'X' : 'O'; 
      const action = this.ai.getAction(state, available);

      moves.push({ state, action, player });
      this.move(action, player);
    }

    const winner = this.checkWinner();
    // Assign rewards after the game is over
    moves.forEach(m => {
      const reward = winner?.winner === m.player ? 1 : (winner?.winner && winner.winner !== m.player) ? -1 : 0;
      this.ai.update(m.state, m.action, reward, this.board, []);
    });
  }

9. State Persistence

These methods orchestrate saving and loading the game state and AI's memory to localStorage.

  saveState() {
    this.ai.save();
    localStorage.setItem('tictactoe_stats', JSON.stringify(this.stats));
  }

  loadState() {
    if (this.ai.load()) {
      const savedStats = localStorage.getItem('tictactoe_stats');
      if (savedStats) {
        this.stats = JSON.parse(savedStats);
      }
      this.updateStats();
      this.setDifficulty(this.ai.difficulty);

      // Update sliders to reflect loaded AI state
      document.getElementById('learningRate').value = this.ai.lr;
      document.getElementById('learningRateValue').textContent = this.ai.lr.toFixed(2);
      document.getElementById('discountFactor').value = this.ai.gamma;
      document.getElementById('discountFactorValue').textContent = this.ai.gamma.toFixed(2);
      document.getElementById('explorationRate').value = this.ai.epsilon;
      document.getElementById('explorationRateValue').textContent = this.ai.epsilon.toFixed(2);

      console.log('✓ Loaded AI state from localStorage');
    }
  }
}

10. Initializing the Game

Finally, add this snippet at the end of game.js to create an instance of the game once the HTML document is loaded.

let game;
window.addEventListener('DOMContentLoaded', () => {
  game = new TicTacToe();
});

This completes our implementation! You now have a fully functional game.js file. If you encountered any issues or want to double-check your work, you can compare your code against the complete source file available on GitHub: https://github.com/mayur9210/tic-tac-toe-ai/blob/main/game.js.

How to Understand the Enhanced Features

Beyond the core Q-learning logic, this implementation includes several enhanced features to create a complete, user-friendly, and educational application. Let's explore what they are and how they work.

1. Adaptive Difficulty Levels

The game supports three distinct difficulty modes to cater to different players:

• Beginner (🌱): This mode is designed for new players. The AI makes random moves 70% of the time, providing a high chance for the player to win and learn the game's rules.

• Intermediate (🎯): This is the standard mode where the AI uses the Q-learning algorithm with an epsilon-greedy strategy. It presents a challenging but fair opponent that improves over time.

• Expert (🔥): This mode switches from reinforcement learning to the classic minimax algorithm. This algorithm plays a perfect game, meaning it is impossible to beat (the best a player can achieve is a draw). This serves as a benchmark for optimal play.

2. Other Enhanced Features

In addition to the difficulty levels, the application includes:

• Real-time AI parameter tuning: The sliders in the UI allow you to adjust the Learning Rate (α), Discount Factor (γ), and Exploration Rate (ϵ) on the fly. This lets you directly observe how different hyperparameters affect the AI's learning speed and performance.

• Persistence with localStorage: The AI automatically saves its Q-table and your game statistics to the browser's local storage. When you close the tab and come back later, the AI will remember everything it has learned.

• Dedicated self-play training mode: The "Train AI" button allows the AI to play 1,000 games against itself in a matter of seconds. This rapidly populates the Q-table and is far more efficient than learning from just human-played games.

Putting It All Together: A Guided Test Run

Once you have the HTML (index.html) and JavaScript (game.js) files in same directory, open the HTML file in a web browser to test all the features. When you open the HTML file, it should look like as shown in the below image.

I have also hosted this file on GitHub Pages if you want to see how it works.

Now that you have the application running, let's walk through how to test the features and witness the AI's learning process firsthand. This interactive testing is the most rewarding part, as you'll see the abstract concepts come to life.

Step 1: Challenge the Untrained AI

When you first load the game, the AI is a blank slate. Its Q-table is empty. Make sure the difficulty is set to 🌱 Beginner and play a game against it. You'll likely find it very easy to beat. It makes random, nonsensical moves because it has no experience. Notice the "States Learned" in the statistics panel is very low.

Step 2: Train the AI

Now for the magic. Click the "Train AI (1000 games)" button. You'll see the yellow training indicator appear with a progress counter. In these few seconds, the AI is playing 1,000 games against itself, rapidly learning from its wins, losses, and draws. For every move in every game, it updates its Q-table, reinforcing good strategies and penalizing bad ones.

Step 3: Challenge the Trained AI

Once training is complete, play another game on 🎯 Medium difficulty. The difference should be dramatic. The AI will now play strategically, blocking your wins and setting up its own. It is no longer a pushover. Check the statistics panel again: you'll see the "States Learned" count has jumped significantly, representing all the new board positions it now understands.

Step 4: Experiment with the Controls

Now that you have a trained AI, experiment with the other features:

• Switch to 🔥 Expert: Play against the minimax algorithm. Notice that you can't win. This demonstrates the power of a perfect-play algorithm.

• Tweak the parameters: Set the Exploration Rate (ε) slider to 0. The AI will become completely deterministic, always picking the move with the highest Q-value. Set it to 0.5, and watch it become more erratic and experimental again.

• Reset the AI: Click the "Reset AI Memory" button. This will wipe its Q-table. If you play against it now, you'll find it's back to its original, untrained state. This confirms that its "intelligence" was stored in the Q-table you just erased.

Verifying the Implementation with Automated Tests

While playing the game gives you a good feel for the AI's behavior, automated tests are crucial for programmatically confirming that the underlying code is correct. This is different from the manual testing you just performed. Here, we are writing code to check our code.

The following test suite validates the three most critical features: difficulty switching, data persistence with localStorage, and the infallibility of the expert minimax AI. You can run these tests by copying and pasting the code into your browser's developer console while the game is open.

function runTests() {
  console.log('🧪 Running enhanced tests...');

  // Test 1: Difficulty switching
  const g1 = new TicTacToe();
  g1.setDifficulty('beginner');
  console.assert(g1.ai.difficulty === 'beginner', '✓ Difficulty switching works');

  // Test 2: localStorage persistence
  const g2 = new TicTacToe();
  g2.ai.q.set('test-state', [1, 2, 3, 4, 5, 6, 7, 8, 9]);
  g2.saveState();
  const g3 = new TicTacToe();
  console.assert(g3.ai.q.has('test-state'), '✓ localStorage persistence works');

  // Test 3: Minimax never loses
  const g4 = new TicTacToe();
  g4.setDifficulty('expert');
  let expertLosses = 0;
  for (let i = 0; i < 100; i++) {
    g4.reset();
    while (!g4.gameOver) {
      const available = g4.getAvailable();
      const move = available[~~(Math.random() * available.length)];
      g4.move(move, 'X');
      if (!g4.gameOver) g4.aiMove();
    }
    const winner = g4.checkWinner();
    if (winner?.winner === 'X') expertLosses++;
  }
  console.assert(expertLosses === 0, '✓ Expert AI never loses');

  console.log('✅ All tests passed!');
}

How these tests work:

1. Difficulty switching: The first test creates a game instance, sets the difficulty, and asserts that the AI's internal property was updated correctly.

2. Persistence: The second test simulates saving the AI's state. It adds a dummy entry to the Q-table, saves it, creates a new game instance (simulating a page reload), and asserts that the new instance successfully loaded the saved data.

3. Expert mode correctness: The third and most rigorous test plays 100 games against the expert AI using random moves for the player. It then asserts that the expert AI never lost a single game, proving the minimax implementation is correct.

You can run these tests in your browser's console after loading the game as shown in the below screenshot.

Advanced Optimizations and Extensions

Now that you have the complete implementation, here are ways to extend it further:

How to Implement Symmetry Reduction

You can reduce the state space by recognizing equivalent board positions:

getCanonicalState(s) {
  const transforms = [
    s, this.rot90(s), this.rot180(s), this.rot270(s),
    this.flip(s), this.flip(this.rot90(s)), 
    this.flip(this.rot180(s)), this.flip(this.rot270(s))
  ];
  return transforms.sort()[0];
}

rot90(s) {
  const b = s.split('');
  return [b[6],b[3],b[0],b[7],b[4],b[1],b[8],b[5],b[2]].join('');
}

rot180(s) {
  return s.split('').reverse().join('');
}

rot270(s) {
  const b = s.split('');
  return [b[2],b[5],b[8],b[1],b[4],b[7],b[0],b[3],b[6]].join('');
}

flip(s) {
  const b = s.split('');
  return [b[2],b[1],b[0],b[5],b[4],b[3],b[8],b[7],b[6]].join('');
}

This symmetry reduction technique speeds up AI learning by recognizing equivalent board positions.

How it works:

• getCanonicalState(): Generates all 8 symmetric versions of a board state (4 rotations + 4 flipped versions) and returns the alphabetically first one as the standard representation

• rot90(): Rotates board 90° clockwise by remapping position indices

• rot180(): Rotates 180° by reversing the board array

• rot270(): Rotates 270° clockwise (or 90° counterclockwise)

• flip(): Mirrors the board horizontally

Why this matters: By storing only canonical states in the Q-table, the AI reduces unique positions from ~5,500 to ~700, making learning 8x faster.

Example: These boards are considered identical:

X-- --- --X
--- = --- = ---
--- --- ---
(original) (180° rotation) (horizontal flip)

All three map to the same canonical state, so the AI only needs to learn one instead of three.

Modify getQ() to use canonical states. This reduces learning time by 8x since the AI recognizes rotated and flipped positions as equivalent.

How to Add Export and Import Functionality

You can also let users share trained AI models:

exportAI() {
  const data = {
    q: Array.from(this.ai.q.entries()),
    stats: this.stats,
    difficulty: this.ai.difficulty,
    timestamp: Date.now()
  };

  const blob = new Blob([JSON.stringify(data)], { type: 'application/json' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `tictactoe-ai-${Date.now()}.json`;
  a.click();
  URL.revokeObjectURL(url);
}

importAI(file) {
  const reader = new FileReader();
  reader.onload = (e) => {
    try {
      const data = JSON.parse(e.target.result);
      this.ai.q = new Map(data.q);
      this.stats = data.stats;
      this.ai.difficulty = data.difficulty;
      this.updateStats();
      this.setStatus('✓ AI imported successfully!');
    } catch (err) {
      this.setStatus('✗ Import failed: Invalid file');
    }
  };
  reader.readAsText(file);
}

These methods enable sharing trained AI models between users. The exportAI() method packages the complete AI state (Q-table, statistics, difficulty, and timestamp) into a JSON object, creates a Blob from the JSON string, generates a temporary download URL, programmatically creates and clicks a download link, then cleans up the URL. The filename includes a timestamp for version tracking.

The importAI() method uses FileReader to asynchronously read an uploaded JSON file, parses it, reconstructs the Map from the array of entries, restores all game state, and updates the display. Error handling catches invalid JSON or corrupted files.

How to Add Q-Value Heatmap Visualization

Here’s how you can visualize the AI's decision-making:

drawQValueHeatmap() {
  const state = this.board;
  const qValues = this.ai.getQ(state);
  const available = this.getAvailable();

  if (available.length === 0) return;

  const maxQ = Math.max(...available.map(i => qValues[i]));
  const minQ = Math.min(...available.map(i => qValues[i]));
  const range = maxQ - minQ || 1;

  this.ctx.globalAlpha = 0.3;
  for (const i of available) {
    const normalized = (qValues[i] - minQ) / range;
    const row = ~~(i / 3);
    const col = i % 3;

    // Green for high Q-values, red for low
    const hue = normalized * 120;
    this.ctx.fillStyle = `hsl(${hue}, 70%, 50%)`;
    this.ctx.fillRect(
      col * this.cellSize + 5,
      row * this.cellSize + 5,
      this.cellSize - 10,
      this.cellSize - 10
    );

    // Draw Q-value
    this.ctx.globalAlpha = 1;
    this.ctx.fillStyle = '#000';
    this.ctx.font = '14px monospace';
    this.ctx.fillText(
      qValues[i].toFixed(2),
      col * this.cellSize + 10,
      row * this.cellSize + 25
    );
  }
  this.ctx.globalAlpha = 1;
}

This visualization method creates a color-coded heatmap showing the AI's confidence in each available move.

It first retrieves Q-values for the current state and finds the min/max values among available positions to normalize the data. For each empty cell, it calculates a normalized score (0 to 1), converts it to a hue value (0° red for low values, 120° green for high values) using HSL color space, and fills the cell with a semi-transparent colored rectangle. It then overlays the actual Q-value as text for precise inspection.

This gives you instant visual feedback about which moves the AI considers most promising. Green cells are good moves, red cells are poor moves.

Common Pitfalls and Solutions

Issue 1: AI Does Not Improve

• Cause: The learning rate is too low or there hasn't been enough training.

• Solution: Increase the learning rate to between 0.2 and 0.3, and train for more than 2000 games.

Issue 2: AI Makes Random Moves

• Cause: The exploration rate is too high after training.

• Solution: Reduce the exploration rate to 0.01 once training is complete.

Issue 3: Slow Performance

• Cause: The state representation or Q-table lookup is inefficient.

• Solution: Use a Map instead of objects and implement state caching.

Issue 4: AI Overfits to One Strategy

• Cause: There isn't enough exploration during training.

• Solution: Begin with a high exploration rate (ε=0.5) and gradually decrease it.

How to Extend This to Other Games

This framework adapts to other games:

• Connect Four: 42-character state, 7 actions (columns)

• Blackjack: State includes hand values and dealer card

• Snake: Continuous states require function approximation

Conclusion

You have built a complete reinforcement learning system in JavaScript. This project demonstrates:

• Core RL concepts with practical implementation

• Clean, maintainable code architecture

• Real-time training and visualization

• Advanced techniques like epsilon decay and self-play

• Three difficulty levels from beginner to expert

• Data persistence with localStorage

• Interactive tooltips for learning

The Q-learning foundation you have implemented powers more advanced techniques like Deep Q-Networks (DQN) used in modern game AI.

Next Steps

Here are some ways to continue learning:

1. Add more difficulty levels with custom parameters

2. Implement state persistence with IndexedDB for larger Q-tables

3. Create multiplayer mode with AI observation

4. Build a neural network version with TensorFlow.js

5. Extend to Connect Four or Chess endgames

Resources for Further Learning

• Reinforcement Learning: An Introduction by Sutton and Barto (free online textbook)

• OpenAI Spinning Up – comprehensive RL resource

• Deep RL Bootcamp – Berkeley video lectures

• Stable-Baselines3 Documentation – production RL implementations

The JavaScript ecosystem moves quickly. One minute, we're building monolithic Node.js servers. The next, it's all about serverless functions and running code at the edge on platforms like Cloudflare or Vercel. Staying current can feel like a full-time job.

Hono is built on top of Web Standards – the same Request and Response objects in your browser – which means your code is naturally portable across almost any JavaScript runtime.

This guide is a deep dive into this powerful little framework, designed to help you build real, production-ready applications. We’ll skip the quick "Hello, World!" and jump straight into the patterns and features you will actually use, with plenty of detailed code examples along the way.

Table of Contents

• What You Will Learn in This Guide

• Prerequisites for Following Along

• How to Set Up a Professional Hono Project

• How to Understand Hono's Core API

• The Context Object in Depth

• How to Use Advanced Features for Production Apps

• Deployment Guide for Hono

What You Will Learn in This Guide

By the end of this tutorial, you will be able to:

• Structure a Hono project for both development and production.

• Implement advanced routing patterns.

• Leverage the full power of the Context object to manage requests and pass data between middleware.

• Write complex custom middleware for authentication, logging, and error handling.

• Validate incoming data using the official Zod validator for robust APIs.

• Build a small, server-rendered application with JSX components.

• Deploy a Hono application to various modern hosting platforms.

Prerequisites for Following Along

This is an in-depth guide, but it assumes you have some foundational knowledge. Before you start, you should have:

• Node.js installed: Version 18 or higher is recommended.

• A code editor: Visual Studio Code is a great choice.

• Familiarity with TypeScript: You should understand basic types, functions, and async/await.

• Basic command-line knowledge: You should be comfortable running commands in your terminal.

How to Set Up a Professional Hono Project

You can get started with Hono using a single command. This will create a new project directory with a recommended structure and configuration files. When prompted, select the nodejs template and choose to install dependencies with your preferred package manager (for example, npm).

npm create hono@latest hono-production-app

The command will guide you through the setup:

> npx create-hono hono-production-app

create-hono version 0.19.2
✔ Using target directory … hono-production-app
✔ Which template do you want to use? nodejs
✔ Do you want to install project dependencies? Yes
✔ Which package manager do you want to use? npm
✔ Cloning the template
✔ Installing project dependencies
🎉 Copied project files
Get started with: cd hono-production-app

Now, navigate into your new directory: cd hono-production-app. Let's look at the files that were created:

• package.json: Defines your project's dependencies and scripts.

• tsconfig.json: The TypeScript configuration file.

• src/index.ts: The entry point of your application.

Now, you can run npm run dev to start your development server. Navigate to http://localhost:3000, and you will see "Hello Hono!".

How to Understand Hono's Core API

Hono's API is designed to be minimal, which makes it easy to learn – yet incredibly powerful.

How to Use Advanced Routing Techniques

You may already know app.get() and app.post() from Express, but Hono's router can do much more.

1. How to Route with Regular Expressions

You can constrain a URL parameter to match a specific regular expression. For example, to make sure an :id parameter only accepts numbers, you can do this:

// Only match routes like /users/123, not /users/abc
app.get('/users/:id{[0-9]+}', (c) => {
  const id = c.req.param('id')
  return c.text(`Fetching data for user ID: ${id}`)
})

2. How to Use Optional and Wildcard Routes

You can define routes that match multiple paths using wildcards (*) or handle optional parameters.

// This will match /files/image.png, /files/docs/report.pdf, and so on.
app.get('/files/*', (c) => {
  // c.req.path will contain the full matched path
  return c.text(`You are accessing the file at: ${c.req.path}`)
})

// The '?' makes the '/:format?' part of the URL optional
// This will match both /api/posts and /api/posts/json
app.get('/api/posts/:format?', (c) => {
  const format = c.req.param('format')
  if (format === 'json') {
    return c.json({ message: 'Here are the posts in JSON format.' })
  }
  return c.text('Here are the posts in plain text.')
})

3. How to Group Routes with app.route()

For larger applications, you should organize your routes into logical groups. The app.route() method is perfect for this. It allows you to create modular routers and mount them on a specific prefix.

Let's create a more complex API structure for a blog.

src/routes/posts.ts

import { Hono } from 'hono'

// Create a new router instance specifically for posts
const posts = new Hono()

posts.get('/', (c) => c.json({ posts: [] }))
posts.post('/', (c) => c.json({ message: 'Post created' }, 201))
posts.get('/:id', (c) => c.json({ post: { id: c.req.param('id') } }))

export default posts

src/routes/authors.ts

import { Hono } from 'hono'

const authors = new Hono()

authors.get('/', (c) => c.json({ authors: [] }))
authors.get('/:id', (c) => c.json({ author: { id: c.req.param('id') } }))

export default authors

src/index.ts

import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { appendTrailingSlash } from 'hono/trailing-slash';
import posts from './routes/posts.js'
import authors from './routes/authors.js'

const app = new Hono()

app.use(appendTrailingSlash());

app.route('/posts/', posts)
app.route('/authors/', authors)

app.get('/', (c) => {
  return c.text('Hello Hono!')
})

serve({
  fetch: app.fetch,
  port: 3000
}, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

This pattern keeps your main index.ts file clean and makes your application much easier to navigate and maintain.

The Context Object in Depth

The Context (c) is the heart of Hono. It's an object that gets passed to every middleware and route handler, containing all the information related to the current request. It's essentially a container for the request (c.req) methods for creating a response (c.json, c.html, c.text), as well as a special property for passing data between middleware (c.set and c.get).

While this covers its most common and useful properties, the full Context object contains more. For a comprehensive list of all available properties and methods, you can refer to the official Hono documentation.

Let's explore how you can use the context object to pass data between middleware and handlers, a crucial technique for things like authentication.

The c.set() and c.get() methods allow you to store and retrieve typed data within the context of a single request.

Replace src/index.ts with this example for authentication:

import { Hono } from 'hono'
import type { Context, Next } from 'hono'

// Define a type for the variables we will store in the context
type AppVariables = {
  user: {
    id: string
    name: string
    roles: string[]
  }
}

// Use a generic to tell our Hono app about the variables type
const app = new Hono<{ Variables: AppVariables }>()

// Middleware to "authenticate" a user from a header
const authMiddleware = async (c: Context, next: Next) => {
  const userId = c.req.header('X-User-ID')
  if (!userId) {
    return c.json({ error: 'Missing X-User-ID header' }, 401)
  }

  // In a real app, you would fetch this from a database
  const user = {
    id: userId,
    name: 'Jane Doe',
    roles: ['admin', 'editor'],
  }

  // Use c.set() to attach the user data to the context
  c.set('user', user)

  await next()
}

app.get('/admin/dashboard', authMiddleware, (c) => {
  // Use c.get() to retrieve the typed user data
  const user = c.get('user')

  if (!user.roles.includes('admin')) {
    return c.json({ error: 'Forbidden' }, 403)
  }

  return c.json({
    message: `Welcome to the admin dashboard, ${user.name}!`,
    userId: user.id,
  })
})

export default app

Let's break down the important parts of the code above.

• Typed context variables: We define a TypeScript type AppVariables and pass it as a generic to our Hono app new Hono<{ Variables: AppVariables }>(). This is a powerful feature that gives us full type-safety for our context variables, preventing typos and ensuring that the data we store and retrieve is exactly what we expect it to be.

• Custom middleware: The authMiddleware is a custom function that runs before our route handler. It inspects the incoming request's headers (c.req.header('X-User-ID')).

• Storing data: If a valid header is found, the middleware uses c.set('user', user) to store the user object on the context. This data is now available to any subsequent middleware or route handler for the same request.

• Retrieving data: The route handler app.get('/admin/dashboard', ...) then uses c.get('user') to retrieve the user object. Hono's type system ensures that c.get('user') returns a variable with the type { id: string; name: string; roles: string[]; }.

• Flow control: If the user is missing or doesn't have the "admin" role, the middleware or handler can immediately send an error response using c.json() and a status code, preventing the request from proceeding further.

Now, run npm run dev.

You can test with curl (add header):

curl -H "X-User-ID: 123" http://localhost:3000/admin/dashboard

This will return a welcome message.

Without the header:

curl http://localhost:3000/admin/dashboard

This will return a 401 error.

This demonstrates how to pass typed data securely and efficiently between middleware and route handlers.

How to Use Advanced Features for Production Apps

Now we're ready to tackle the features you'll use every day in production: advanced middleware, data validation, and building full-stack applications.

How to Use Advanced Middleware Patterns

Hono has a powerful set of built-in middleware, including JWT and caching. These are not separate libraries you have to install, but rather functions that come with the Hono package itself.

Step 1: Replace src/index.ts with this example for JWT and caching:

import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { jwt, sign } from 'hono/jwt'

const app = new Hono()
const SECRET = 'my-secret-key' // Use an environment variable in production!

// Create a simple in-memory cache store
const cacheStore = new Map();

// Custom caching middleware for Node.js
app.use('/api/public-data', async (c, next) => {
  const cacheKey = c.req.url;

  // Check if the response is in our cache
  if (cacheStore.has(cacheKey)) {
    const cachedItem = cacheStore.get(cacheKey);
    console.log('Serving from custom in-memory cache.');
    return new Response(cachedItem.body, { headers: cachedItem.headers });
  }

  // If not in cache, proceed to the route handler
  await next();

  // After the handler returns, clone and store the response
  if (c.res) {
    const newResponse = c.res.clone();
    const body = await newResponse.text();
    const headers = Object.fromEntries(newResponse.headers.entries());
    cacheStore.set(cacheKey, { body, headers });
    console.log('Storing response in custom in-memory cache.');
  }
});

// Login to get a JWT
app.post('/login', async (c) => {
  const { username } = await c.req.json()
  if (username === 'admin') {
    const payload = {
      sub: username,
      role: 'admin',
      exp: Math.floor(Date.now() / 1000) + 60 * 5, // 5 minutes expiration
    }
    const token = await sign(payload, SECRET)
    return c.json({ token })
  }
  return c.json({ error: 'Invalid credentials' }, 401)
})

// Protected route
app.get(
  '/api/protected',
  jwt({ secret: SECRET }),
  (c) => {
    const payload = c.get('jwtPayload')
    return c.json({ message: 'You have access!', payload })
  }
)

// Cached route
app.get(
  '/api/public-data',
  async (c) => {
    console.log('Executing handler with delay...');
    await new Promise(resolve => setTimeout(resolve, 1000)) // Simulate a delay
    return c.json({ data: 'This is some public data that rarely changes.' })
  }
)

serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

The code above shows two different types of middleware in action.

First, JWT middleware (jwt) is a powerful way to secure your routes. When we call jwt({ secret: SECRET }), we're telling Hono to check for a valid JWT in the Authorization header of the incoming request. If a valid token is found, it decodes the payload and attaches it to the context, where we can retrieve it with c.get('jwtPayload'). If no token is found or if the token is invalid, the middleware automatically stops the request and returns a 401 Unauthorized error.

We also have Custom Cache Middleware which demonstrates the power of Hono's middleware system for in-memory caching. The middleware first checks an in-memory Map to see if a response for the current URL already exists. If it does, it immediately returns the cached response, preventing the route handler from ever being executed. If the response is not in the cache, it allows the request to continue to the handler. After the handler returns, the middleware intercepts the response and stores a copy in the cache before sending it back to the client. This is a robust and reliable pattern for Node.js environments.

Step 2: Run npm run dev.

Step 3: Test the login endpoint with curl:

First, let's test the login endpoint to get a JWT. Open a new terminal and run the following command. The command sends a POST request to the /login endpoint with username: "admin" in the request body.

curl -X POST http://localhost:3000/login -H "Content-Type: application/json" -d '{"username": "admin"}'

This will return a JSON object with a JWT. Copy this token for the next step.

Now, let's test the protected route. We'll use the token we just received in the Authorization header. Replace <your_jwt_token> with the token you copied.

curl http://localhost:3000/api/protected -H "Authorization: Bearer <your_jwt_token>"

You should get a success message with the decoded payload.

Finally, let's test the cached route. You’ll need to run a production build and run the file with node for this to work.

First, run the following command. The 1000 millisecond delay in the code will make this request take about a second.

curl -o /dev/null -s -w 'Total: %{time_total}s\n' http://localhost:3000/api/public-data

Immediately run the exact same command again. This time, the response will be almost instantaneous because our custom cache middleware served the response directly from its in-memory store, completely bypassing the setTimeout in the route handler. Run it a third time, and you'll see a similar near-instantaneous response.

Here's an example of what your terminal output should look like when testing the cache. The first request took around 1 second, but subsequent requests were a matter of milliseconds.

How to Create a Global Error Handler

You can define a single global error handler with app.onError(). This is useful for handling unexpected errors in a centralized way, such as validation failures.

Add the following code to your src/index.ts:

app.get('/users/:id', (c) => {
  const id = c.req.param('id')
  if (isNaN(Number(id))) {
    throw new Error('User ID must be a number.')
  }
  return c.text(`User ID is ${id}`)
})

app.onError((err, c) => {
  console.error(`${err}`)
  return c.json({
    success: false,
    message: err.message,
  }, 500)
})

Now, if you visit http://localhost:3000/users/abc, you will get a JSON error response instead of an uncaught exception.

How to Handle Validation with Zod

For robust APIs, data validation is essential. Hono integrates seamlessly with Zod, a popular TypeScript-first schema validation library.

Step 1: Install the necessary dependencies:

npm install zod @hono/zod-validator

Step 2: Replace src/index.ts with the validation example:

import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { z } from 'zod'
import { zValidator } from '@hono/zod-validator'

const app = new Hono()

// Define a Zod schema for the user creation data
const createUserSchema = z.object({
  username: z.string().min(3).max(20),
  email: z.string().email(),
  age: z.number().int().positive(),
  tags: z.array(z.string()).optional(),
})

app.post(
  '/users',
  zValidator('json', createUserSchema), // Use zValidator middleware
  (c) => {
    // The validated data is available on c.req.valid()
    const user = c.req.valid('json')
    console.log(`Creating user: ${user.username} with email ${user.email}`)
    return c.json({
      success: true,
      message: 'User created successfully!',
      user: user,
    }, 201)
  }
)

serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

This is how the Zod validation is working:

1. We first define a schema called createUserSchema using z.object(). This schema is a blueprint for the expected data structure. We use Zod's built-in methods like z.string().min(3), z.string().email(), and z.number().int().positive() to specify validation rules for each property. For example, username must be a string between 3 and 20 characters, email must be a valid email format, and age must be a positive integer.

2. We then apply the zValidator middleware to our route handler. The first argument, 'json', tells the middleware to validate the incoming request's JSON body. The second argument, createUserSchema, tells it which schema to use for the validation.

3. The zValidator middleware automatically does the heavy lifting. When a request hits the /users endpoint, it will parse the JSON body and attempt to validate it against createUserSchema. If the data is invalid (for example, the email is not in a valid format), the middleware will immediately stop the request and return a 400 Bad Request status with a detailed error message, all without us having to write any manual checks.

4. If the data is valid, the middleware makes it available on the Context object, which we can access with c.req.valid('json'). Hono's type system ensures that this data is correctly typed according to the Zod schema, so we can use it safely in our handler.

Step 3: Run npm run dev.

Step 4: Test with curl (valid data):

curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"username": "testuser", "email": "test@example.com", "age": 25}'

This will return a success message.

Test with invalid data (for example, bad email):

curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"username": "testuser", "email": "invalid-email", "age": 25}'

This will automatically return a 400 status with a detailed error message from Zod.

How to Build a Full-Stack App with JSX

Hono supports server-side rendering with JSX, allowing you to build full-stack applications without needing a separate framework.

Step 1: Create src/components/Layout.tsx:

import { html } from 'hono/html'

export const Layout = (props: { title: string; children?: any }) => html`
  <!DOCTYPE html>
  <html>
    <head>
      <title>${props.title}</title>
      <style>
        body { font-family: sans-serif; background: #f4f4f4; color: #333; }
        .container { max-width: 800px; margin: 2rem auto; padding: 1rem; background: white; border-radius: 8px; }
        header { border-bottom: 1px solid #ccc; padding-bottom: 1rem; }
        footer { margin-top: 2rem; text-align: center; font-size: 0.8rem; color: #777; }
      </style>
    </head>
    <body>
      <div class="container">
        <header>
          <h1>${props.title}</h1>
        </header>
        <main>
          ${props.children}
        </main>
        <footer>
          <p>Powered by Hono</p>
        </footer>
      </div>
    </body>
  </html>
`

Step 2: Create src/components/PostItem.tsx:

export const PostItem = (props: { post: { id: number; title: string; author: string } }) => (
  <article style="border-bottom: 1px solid #eee; padding: 1rem 0;">
    <h3><a href={`/posts/${props.post.id}`}>{props.post.title}</a></h3>
    <p><em>By {props.post.author}</em></p>
  </article>
)

Step 3: Update src/index.tsx:

import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { Layout } from './components/Layout'
import { PostItem } from './components/PostItem'

const app = new Hono()

// Mock data
const posts = [
  { id: 1, title: 'Getting Started with Hono', author: 'Alice' },
  { id: 2, title: 'Advanced Middleware Patterns', author: 'Bob' },
  { id: 3, title: 'Deploying Hono to the Edge', author: 'Charlie' },
]

app.get('/', (c) => {
  return c.html(
    <Layout title="My Hono Blog">
      <h2>Recent Posts</h2>
      {posts.length > 0
        ? posts.map(post => <PostItem post={post} />)
        : <p>No posts yet!</p>
      }
    </Layout>
  )
})

serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

Make sure to update the dev script in your package.json file to have src/index.tsx as the starting point.

"dev": "tsx watch src/index.tsx"

Step 4: Run npm run dev and visit http://localhost:3000. You will see a fully rendered blog page with the list of posts.

Deployment Guide for Hono

You have built your application, and now it's time to share it with the world. Here’s how you can deploy your Hono app to some of the most popular platforms.

How to Deploy to Node.js

For a traditional server environment, you can use the @hono/node-server adapter and a process manager like pm2 for production.

src/index.ts:

import { serve } from '@hono/node-server'
import app from './app' // Assuming your Hono app is in app.ts

serve({ fetch: app.fetch, port: 3000 })

You will then build your TypeScript to JavaScript and run pm2 start dist/index.js to run it in the background.

How to Deploy to Cloudflare Workers

Hono's true power lies in its portability. The create hono command can set up a project specifically for Cloudflare Workers.

Run the following command and select the cloudflare-workers template:

npm create hono@latest my-app-hono-cloudflare-worker

create-hono version 0.19.2
✔ Using target directory … my-app-hono-cloudflare-worker
? Which template do you want to use?
  aws-lambda
  bun
❯ cloudflare-workers
  cloudflare-workers+vite
  deno
  fastly
  lambda-edge

The setup process is identical to the Node.js example, but the project structure is optimized for Cloudflare.

Once the project is set up, you only need to type one command to deploy your application to Cloudflare:

wrangler deploy

This command will prompt you to log in to your Cloudflare account and will handle the entire deployment process automatically.

Conclusion

You've made it! We’ve covered a lot in this guide. You started with a professional project setup and moved all the way through advanced routing, context management, complex middleware patterns, robust data validation, and full-stack JSX components.

You now have the knowledge and the tools to build serious, production-ready applications with Hono. Its simple API doesn't limit its power. Rather, it enhances it by getting out of your way and letting you focus on building great features. And with its helpful portability, you can be confident that the application you build today can be deployed to the platforms of tomorrow.

The web development ecosystem will continue to evolve, but by building on Web Standards, Hono is a framework that's built to last.

To continue your journey, I highly recommend exploring the official Hono documentation, which is full of even more examples and guides.