Status: 0.x - v0 MVP + real-time plugins + unread counts + browser client + reactions + search + group chats + mentions + forwarding, live on npm. The v0 MVP (core engine, HTTP handler, real-time SSE, Postgres adapter) plus the opt-in real-time plugins - typing(), presence(), and receipts(), all shipping today inside @chatpack/core under the @chatpack/core/plugins subpath (see Real-time plugins) - are published and installable now, along with the first-party @chatpack/client, which provides the matching typed REST, SSE, and React client. The API is young - expect minor breaking changes before 1.0. Follow along or contribute.

Why

Every app that needs messaging ends up rebuilding the same things: conversations, messages, permissions, read receipts, real-time delivery, group membership and roles, and countless edge cases.

Chatpack removes that repetition - the same way BetterAuth did for authentication. You bring your auth and your frontend; Chatpack gives you a small, well-designed chat backend that just works.

Real-time comes built in: your frontend opens one EventSource and gets live messages with automatic reconnection and missed-message backfill - no WebSocket server, no Socket.IO, no reconnect code to write.

How it fits together

Your frontend  ──  fetch("/api/chat/…")  +  EventSource("/api/chat/stream")
      │
      ▼
chat.handler()        one Web-standard handler (Request → Response)
      │
      ├── auth hook   your session → { id: userId }     (you own users)
      ▼
chat.api.*            domain logic, permissions         (also callable directly)
      │
      ▼
StorageAdapter        memory · Drizzle/Postgres · Drizzle/SQLite · Turso/libSQL · Supabase · your own
      │
      ▼
Your database

Quickstart

Prefer learning from a complete app? examples/messenger is a full 1:1 messenger - sidebar, live messages, read receipts - in vanilla HTML+JS with a step-by-step tutorial README.

1. Install

Both packages are needed for the quickstart - @chatpack/core is the engine, @chatpack/adapter-memory is the storage it plugs into:

# pick your package manager
npm  install @chatpack/core @chatpack/adapter-memory
pnpm add     @chatpack/core @chatpack/adapter-memory
bun  add     @chatpack/core @chatpack/adapter-memory

Bun note: if Bun's supply-chain guard (minimumReleaseAge) is enabled, versions published in the last 24 h are skipped and Bun silently resolves an older release. If you get an unexpectedly old version right after a release, that's the guard - not a broken package. Check with npm view @chatpack/core dist-tags.

2. Create your chat server

// lib/chat.ts
import { chatpack } from "@chatpack/core";
import { memoryAdapter } from "@chatpack/adapter-memory";

export const chat = chatpack({
  storage: memoryAdapter(),
  // resolve the current user from a request - the ONLY auth touchpoint.
  // Concrete example with a session cookie (works with any auth library):
  auth: async (req) => {
    const session = await getSessionFromCookie(req.headers.get("cookie"));
    return session ? { id: session.userId } : null;
  },
});

The auth hook must return ChatpackUser | null - an object with at least { id: string } (extra fields are allowed and ignored), or null for unauthenticated requests. Returning a bare string is treated as unauthenticated and every request will get a 401.

Prefer cookie-based sessions over Authorization headers: the browser sends cookies automatically on every request - including the SSE stream in step 6, where custom headers are impossible.

The hook receives a raw Web-standard Request - there is no request.cookies helper. Parse the cookie header yourself:

server.ts

Copy

// demo auth: a plain cookie naming the user (swap for your auth library)
auth: (request) => {
  const cookie = request.headers.get("cookie") ?? "";
  const id = /(?:^|;\s*)demo_user=([^;]+)/.exec(cookie)?.[1] ?? null;
  return id ? { id: decodeURIComponent(id) } : null;
},

Setting the demo cookie in an embedded preview (Lovable, v0, Bolt, ...)? Those editors show your app inside a cross-site iframe, where browsers silently drop SameSite=Lax cookies - the app 401s in the preview pane but works in a real tab. Set demo cookies with iframe-proof attributes:

ts

Copy

document.cookie = "demo_user=alice; Path=/; Max-Age=86400; SameSite=None; Secure; Partitioned";

For production, swap the storage line for Postgres - @chatpack/adapter-drizzle:

import { drizzle } from "drizzle-orm/node-postgres";
import { drizzleAdapter } from "@chatpack/adapter-drizzle";

export const chat = chatpack({
  storage: drizzleAdapter(drizzle(process.env.DATABASE_URL!)),
  auth: async (req) => getSessionUser(req),
});

If your application already uses Prisma ORM 7, use the server-only @chatpack/adapter-prisma adapter. Copy its Prisma models and migration into your app, generate your own client, and pass it to prismaAdapter(client). Verified provider is PostgreSQL 16; Prisma 8 and other providers are not claimed compatible.

No direct Postgres connection string? Platforms that only expose a database client (Supabase's JS client, Convex, and most AI-builder clouds) are supported through a custom StorageAdapter. The full guide - reference schema, invariants, skeleton, and a verification checklist - is Part 2 of llms.txt.

Building with an AI assistant or app builder? llms.txt is the single-fetch integration guide (hard rules, wiring, per-framework mount recipes, preview-iframe cookie recipe, verification steps). It also ships inside every @chatpack/* npm package as llms.txt - point your agent at node_modules/@chatpack/core/llms.txt.

For Turso/libSQL, install @chatpack/adapter-turso, @libsql/client, and drizzle-orm, then run its exported migration statements before creating the Chatpack instance. See the Turso adapter guide.

For MySQL 8, install @chatpack/adapter-mysql, mysql2, and drizzle-orm, create a server-side transaction-capable pool, and run its exported migration statements before creating the Chatpack instance. See the MySQL adapter guide. This package does not claim MariaDB, PlanetScale, Aurora, serverless/HTTP drivers, or edge-runtime support.

Using a coding agent (Claude Code, Cursor, Codex)? Install the Chatpack agent skill into your app's repo so the agent follows the correct workflow automatically:

Terminal

Copy

npx skills add chddaniel/chatpack

For MCP clients, @chatpack/mcp provides read-only tools for documentation search, framework guides, and React UI source. See its README for local setup and client configuration.

3. Mount the API (Next.js App Router)

// app/api/chat/[...chatpack]/route.ts
import { chat } from "@/lib/chat";
export const { GET, POST, PATCH, DELETE, PUT } = chat.handler();

Or, with the @chatpack/next helper (same result, reads better):

import { toNextRouteHandlers } from "@chatpack/next";
import { chat } from "@/lib/chat";
export const { GET, POST, PATCH, DELETE, PUT } = toNextRouteHandlers(chat);

The route file must be a catch-all ([...chatpack] in Next.js) - Chatpack serves many sub-paths under basePath (default /api/chat), so a single app/api/chat/route.ts would 404 everything but the root.

Never hand-write your own message or stream routes. The one handler already serves every route - conversations, messages, read-state, plugins, and the SSE stream. Custom /api/messages-style routes split state and break live delivery.

Your chat backend is now live at /api/chat - find-or-create conversations, send/list/edit/delete messages, read-state, and a live SSE stream at /api/chat/stream, with your auth enforced on every request.