Required dependencies

This is a Python backend, not a Node.js package. Install Python dependencies via pip inside a virtualenv:

pip install chainlit
# Or to install from the local source checkout:
pip install -e ./source

For Node.js projects that proxy to this backend, no additional npm packages are required beyond your existing HTTP/WebSocket client. If you use the chainlit-node bridge package, install it as:

npm install chainlit-node

If you need storage adapters, install optional extras:

pip install chainlit[azure]   # Azure Blob storage
pip install chainlit[s3]      # AWS S3 storage
pip install chainlit[literalai] # LiteralAI data layer

No native build steps, pod installs, or npx prebuild commands are required.

Project setup

1. Copy the source/ directory into your repository, for example at backend/chainlit/.
2. Create a Python virtualenv and install dependencies: pip install -e backend/chainlit.
3. Create a .env file (or export env vars) with required configuration:

   CHAINLIT_AUTH_SECRET=your-random-secret-min-32-chars
   CHAINLIT_URL=http://localhost:8000
   DATABASE_URL=sqlite:///./chainlit.db   # or postgres:// for production
   OAUTH_GITHUB_CLIENT_ID=...
   OAUTH_GITHUB_CLIENT_SECRET=...
   

4. Create your app entry point (e.g., app.py) in your project root and import from chainlit.
5. Start the server: chainlit run app.py --port 8000 or python -m chainlit run app.py.
6. From your Node.js/TypeScript layer, proxy WebSocket and HTTP requests to http://localhost:8000. The Chainlit server exposes a Socket.IO endpoint at /socket.io and a REST API at /api.
7. For TypeScript type safety at the boundary, model the Chainlit HTTP API responses using the types documented in source/types.py.

Public API

Because this is a Python package, the "API" below is described as the Python signatures you will call in your app.py, which the Node.js layer communicates with over HTTP/WebSocket.

cl.Message

// Equivalent HTTP payload posted to /api/message by Node.js proxy
interface ChainlitMessage {
  id: string;
  content: string;
  author: string;
  type: "user_message" | "ai_message" | "system_message";
  createdAt: string;
  elements?: ChainlitElement[];
}

Message is the core communication primitive. Send it from Python to stream responses to the connected frontend. The Node.js proxy receives these events over Socket.IO and forwards them to the browser client.

cl.Step

// Socket.IO event payload for a reasoning step
interface ChainlitStep {
  id: string;
  name: string;
  type: "llm" | "tool" | "retrieval" | "embedding" | "rerank" | "run";
  input?: string;
  output?: string;
  parentId?: string;
  createdAt: string;
}

Step models an individual node in an LLM reasoning trace. Use it when you want to surface intermediate tool calls or chain steps to the UI for transparency.

cl.Action

// UI button action descriptor received from the frontend
interface ChainlitAction {
  id: string;
  name: string;
  value: string;
  label?: string;
  description?: string;
}

Action represents a clickable button rendered inside a message. When the user clicks it, a Socket.IO event fires and your Python @cl.action_callback handler is invoked.

Working examples

Scenario - Node.js proxy forwarding chat messages to Chainlit

A TypeScript Express server receives a POST from the browser, forwards it to the Chainlit backend, and streams the response back.

import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";

const app = express();

// Proxy all Chainlit API and Socket.IO traffic to the Python backend
app.use(
  ["/api", "/socket.io", "/public"],
  createProxyMiddleware({
    target: "http://localhost:8000",
    changeOrigin: true,
    ws: true, // enable WebSocket proxying for Socket.IO
  })
);

app.listen(3000, () => {
  console.log("Node proxy listening on port 3000");
});

Scenario - Authenticating a user via JWT before connecting to Chainlit

import axios from "axios";
import jwt from "jsonwebtoken";

const CHAINLIT_AUTH_SECRET = process.env.CHAINLIT_AUTH_SECRET!;

// Generate a token your frontend passes as ?token= in the Socket.IO handshake
function issueChainlitToken(userId: string, email: string): string {
  return jwt.sign(
    { id: userId, email, role: "USER" },
    CHAINLIT_AUTH_SECRET,
    { expiresIn: "8h" }
  );
}

// Example: login endpoint in Express
import { Request, Response } from "express";
export function loginHandler(req: Request, res: Response) {
  const { userId, email } = req.body as { userId: string; email: string };
  const token = issueChainlitToken(userId, email);
  res.json({ token });
}

Scenario - Calling the Chainlit REST API to retrieve conversation history

import axios from "axios";

interface ChainlitThread {
  id: string;
  createdAt: string;
  steps: Array<{
    id: string;
    name: string;
    output: string;
    type: string;
  }>;
}

async function getThreadHistory(
  threadId: string,
  authToken: string
): Promise<ChainlitThread> {
  const response = await axios.get<ChainlitThread>(
    `http://localhost:8000/api/project/thread/${threadId}`,
    {
      headers: { Authorization: `Bearer ${authToken}` },
    }
  );
  return response.data;
}

// Usage
const thread = await getThreadHistory("thread-uuid-here", "your-jwt-token");
console.log(thread.steps.map((s) => s.output));

File walkthrough

• auth/ - jwt.py signs/verifies JWTs; cookie.py manages httpOnly auth cookies. These are called by server.py on every authenticated request.
• cli/ - Exposes chainlit run, chainlit hello, and chainlit deploy CLI commands.
• data/ - base.py defines the abstract BaseDataLayer interface; concrete implementations in sql_alchemy.py, dynamodb.py, literalai.py are selected via env var. storage_clients/ handles binary file uploads to S3/GCS/Azure.
• discord/ - app.py bootstraps a Discord.py bot that routes messages into Chainlit sessions.
• langchain/ - callbacks.py implements BaseCallbackHandler to forward LangChain run events to Chainlit steps.
• langflow/ - Thin shim wiring LangFlow output into Chainlit messages.
• llama_index/ - callbacks.py implements LlamaIndex BaseCallbackHandler for step tracing.
• mistralai/ - Patches the MistralAI client to emit Chainlit steps.
• openai/ - Instruments the OpenAI client for automatic step and message capture.
• sample/ - hello.py is the minimal "echo bot" demo; starters_demo.py shows starter prompt buttons.
• semantic_kernel/ - Integration bridge for Microsoft Semantic Kernel pipelines.
• slack/ - app.py bootstraps a Slack Bolt app that routes Slack messages into Chainlit.
• teams/ - Microsoft Teams Bot Framework adapter.
• translations/ - JSON locale files loaded by translations.py for UI string i18n.
• __init__.py - Re-exports all public symbols (Message, Step, Action, decorators, etc.) as the chainlit package surface.
• server.py - Builds the FastAPI app, registers all HTTP routes, mounts static files, and wires Socket.IO.
• socket.py - Registers Socket.IO event handlers (connect, disconnect, message, action).
• session.py - Manages the lifecycle of a WebSocket session including user binding and cleanup.
• context.py - Stores the current ChainlitContext in a contextvars.ContextVar so handlers are async-safe.
• config.py - Reads config.toml and environment variables into a singleton ChainlitConfig.
• types.py - Pydantic models shared across the codebase (thread, step, feedback, pagination types).
• user.py - User dataclass with identifier, metadata, and display_name.
• message.py - Message, AskUserMessage, AskFileMessage with send() and stream_token() async methods.
• step.py - Step context manager; use as async with cl.Step(name="my-step") as step:.
• action.py - Action dataclass sent alongside messages to render clickable buttons.
• element.py - Image, File, Audio, Video, Pdf, Text element models attached to messages.
• emitter.py - Low-level Socket.IO emit wrapper; not called directly by application code.
• sync.py - run_sync() helper to call async Chainlit code from synchronous frameworks.
• user_session.py - Dict-like store scoped to the current user session (cl.user_session.set/get).
• chat_context.py - Accumulates the full message history for the current chat.
• chat_settings.py - ChatSettings lets you define a settings panel with InputWidget fields.
• input_widget.py - Select, Slider, Switch, TextInput, NumberInput, Tags widget definitions.
• mode.py - CopilotMode, ChatMode enums controlling UI layout.
• mcp.py - Model Context Protocol tool registration and dispatch.
• oauth_providers.py - Registry of built-in OAuth2 providers (GitHub, Google, Azure AD, Okta, Auth0, etc.).
• markdown.py - Strips or processes markdown for plain-text fallback rendering.
• cache.py - @cl.cache decorator for memoising expensive calls across hot-reloads.
• callbacks.py - @cl.on_message, @cl.on_chat_start, @cl.on_chat_end decorator registration.
• logger.py - Configures loguru logger with level from env.
• secret.py - Helpers for reading secrets from env or secret-manager backends.
• sidebar.py - Sidebar container for persistent side-panel elements.
• version.py - Exposes __version__ string.
• utils.py - Miscellaneous helpers (file-type detection, ID generation, etc.).
• _utils.py - Private helpers not part of the public API.
• translations.py - Loads and merges locale JSON at startup.

Common pitfalls and fixes

• CHAINLIT_AUTH_SECRET too short: Chainlit requires the secret to be at least 32 characters; shorter values raise a startup error. Fix: generate with openssl rand -hex 32.
• Socket.IO version mismatch between Node.js proxy and Python server: Chainlit uses Socket.IO protocol v4; ensure your Node.js socket.io-client is v4.x. Fix: npm install socket.io-client@4.
• CORS errors when proxying: The Chainlit server defaults to allowing only its own origin. Fix: set CHAINLIT_URL to the exact origin of your Node.js proxy and ensure the proxy sends the correct Origin header.
• DATABASE_URL not set causes silent fallback to in-memory storage: Conversation history will not persist across restarts. Fix: always set DATABASE_URL or LITERAL_API_KEY explicitly in production.
• Hot-reload drops WebSocket sessions: Running chainlit run app.py --watch restarts the server on file changes, disconnecting all clients. Fix: disable --watch in production and use a process manager (gunicorn + uvicorn workers).
• LangChain / LlamaIndex callback not tracing: The callback handler must be passed explicitly to the chain/index run() call, not set globally. Fix: pass callbacks=[cl.LangchainCallbackHandler()] to every chain invocation.

Vibe-coding prompt template

I have purchased the `chainlit-node` AVCP block and placed its source in
`backend/chainlit/`. I also have a copy of `USAGE.md` in the same directory.

Please help me integrate the Chainlit Python backend into my project step by step:

1. Read `USAGE.md` and `backend/chainlit/source/__init__.py` to understand
   the public API.
2. Set up a Python virtualenv, install the package from
   `backend/chainlit/source/`, and create a `app.py` entry point that uses
   `@cl.on_message` to echo messages back.
3. Add an Express/TypeScript proxy server that forwards `/api` and `/socket.io`
   traffic to the Chainlit backend running on port 8000, following the pattern
   in USAGE.md "Scenario - Node.js proxy forwarding chat messages to Chainlit".
4. Wire JWT authentication so my existing Node.js auth layer issues tokens
   signed with `CHAINLIT_AUTH_SECRET` that Chainlit will accept, following
   "Scenario - Authenticating a user via JWT".
5. Show me how to retrieve conversation thread history from the Chainlit REST
   API in TypeScript, following "Scenario - Calling the Chainlit REST API".
6. Point out any env vars I must set and any version-pinning issues to avoid,
   referencing the "Common pitfalls and fixes" section.

Use only the real exports and file paths visible in `USAGE.md`. Do not invent
any APIs not present in the source.

License and credit

The Chainlit backend is released under the Apache 2.0 License. See source/LICENSE if present in this block, or refer to the upstream repository at https://github.com/Chainlit/chainlit. The upstream Python package is chainlit on PyPI. This AVCP block redistributes the backend source as-is; consult the upstream license before commercial redistribution.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.