# Technical Documentation: Chainlit/chainlit > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/Chainlit/chainlit) ### Overview (`backend/README.md`)

Welcome to Chainlit 👋

Build python production-ready conversational AI applications in minutes, not weeks ⚡️

> ⚠️ **Notice:** Chainlit is now community-maintained. > > As of May 1st 2025, the original Chainlit team has stepped back from active development. The project is maintained by @Chainlit/chainlit-maintainers under a formal Maintainer Agreement. > > Maintainers are responsible for code review, releases, and security. > Chainlit SAS provides no warranties on future updates. > > Want to help maintain? [Apply here →](https://docs.google.com/forms/d/e/1FAIpQLSf6CllNWnKBnDIoj0m-DnHU6b0dj8HYFGixKy-_qNi_rD4iNA/viewform)

Website • Documentation • Chainlit Help • Cookbook

https://github.com/user-attachments/assets/b3738aba-55c0-42fa-ac00-6efd1ee0d148 ## Installation Open a terminal and run: ```sh pip install chainlit chainlit hello ``` If this opens the `hello app` in your browser, you're all set! ### Development version The latest in-development version can be installed straight from GitHub with: ```sh pip install git+https://github.com/Chainlit/chainlit.git#subdirectory=backend/ ``` (Requires Node and pnpm installed on the system.) ## 🚀 Quickstart ### 🐍 Pure Python Create a new file `demo.py` with the following code: ```python import chainlit as cl @cl.step(type="tool") async def tool(): # Fake tool await cl.sleep(2) return "Response from the tool!" @cl.on_message # this function will be called every time a user inputs a message in the UI async def main(message: cl.Message): """ This function is called every time a user inputs a message in the UI. It sends back an intermediate response from the tool, followed by the final answer. Args: message: The user's message. Returns: None. """ # Call the tool tool_res = await tool() await cl.Message(content=tool_res).send() ``` Now run it! ```sh chainlit run demo.py -w ``` Quick Start

## 📚 More Examples - Cookbook You can find various examples of Chainlit apps [here](https://github.com/Chainlit/cookbook) that leverage tools and services such as OpenAI, Anthropiс, LangChain, LlamaIndex, ChromaDB, Pinecone and more. Tell us what you would like to see added in Chainlit using the Github issues or on [Discord](https://discord.gg/k73SQ3FyUh). ## 💁 Contributing As an open-source initiative in a rapidly evolving domain, we welcome contributions, be it through the addition of new features or the improvement of documentation. For detailed information on how to contribute, see [here](/CONTRIBUTING.md). ## 📃 License Chainlit is open-source and licensed under the [Apache 2.0](LICENSE) license. --- ### Overview (`docs/README.md`) # Documentation for Chainlit developers, contributors, and AI coding assistants. See also: - [CONTRIBUTING.md](../CONTRIBUTING.md) — contribution guidelines - [CHANGELOG.md](../CHANGELOG.md) — release history ## Research Internal notes on CI, tooling, and test layout: - [CI cache optimization](research/ci-cache-optimization.md) - [Copilot type-checking](research/copilot-type-checking.md) - [E2E parallel execution](research/e2e-parallel-execution.md) --- ### Overview (`libs/react-client/README.md`) ## Overview The `@chainlit/react-client` package provides a set of React hooks as well as an API client to connect to your [Chainlit](https://github.com/Chainlit/chainlit) application from any React application. The package includes hooks for managing chat sessions, messages, data, and interactions. ## Installation To install the package, run the following command in your project directory: ```sh npm install @chainlit/react-client ``` This package use [Recoil](https://github.com/facebookexperimental/Recoil) to manage its state. This means you will have to wrap your application in a recoil provider: ```tsx import React from 'react'; import ReactDOM from 'react-dom/client'; import { RecoilRoot } from 'recoil'; import { ChainlitAPI, ChainlitContext } from '@chainlit/react-client'; const CHAINLIT_SERVER_URL = 'http://localhost:8000'; const apiClient = new ChainlitAPI(CHAINLIT_SERVER_URL, 'webapp'); ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render( ); ``` ## Usage ### `useChatSession` This hook is responsible for managing the chat session's connection to the WebSocket server. #### Methods - `connect`: Establishes a connection to the WebSocket server. - `disconnect`: Disconnects from the WebSocket server. - `setChatProfile`: Sets the chat profile state. #### Example ```jsx import { useChatSession } from '@chainlit/react-client'; const ChatComponent = () => { const { connect, disconnect, chatProfile, setChatProfile } = useChatSession(); // Connect to the WebSocket server useEffect(() => { connect({ userEnv: { /* user environment variables */ } }); return () => { disconnect(); }; }, []); // Rest of your component logic }; ``` ### `useChatMessages` This hook provides access to the chat messages and the first user message. #### Properties - `messages`: An array of chat messages. - `firstUserMessage`: The first message from the user. #### Example ```jsx import { useChatMessages } from '@chainlit/react-client'; const MessagesComponent = () => { const { messages, firstUserMessage } = useChatMessages(); // Render your messages return (

{messages.map((message) => (

{message.output}

))}

); }; ``` ### `useChatData` This hook provides access to various chat-related data and states. #### Properties - `actions`: An array of actions. - `askUser`: The current ask user state. - `avatars`: An array of avatar elements. - `chatSettingsDefaultValue`: The default value for chat settings. - `chatSettingsInputs`: The current chat settings inputs. - `chatSettingsValue`: The current value of chat settings. - `connected`: A boolean indicating if the WebSocket connection is established. - `disabled`: A boolean indicating if the chat is disabled. - `elements`: An array of chat elements. - `error`: A boolean indicating if there is an error in the session. - `loading`: A boolean indicating if the chat is in a loading state. - `tasklists`: An array of tasklist elements. #### Example ```jsx import { useChatData } from '@chainlit/react-client'; const ChatDataComponent = () => { const { loading, connected, error } = useChatData(); // Use the data to render your component if (loading) return

; if (error) return

Error connecting to chat...

; if (!connected) return

Disconnected...

; // Rest of your component logic }; ``` ### `useChatInteract` This hook provides methods to interact with the chat, such as sending messages, replying, and updating settings. #### Methods - `callAction`: Calls an action. - `clear`: Clears the chat session. - `replyMessage`: Replies to a message. - `sendMessage`: Sends a message. - `stopTask`: Stops the current task. - `setIdToResume`: Sets the ID to resume a thread. - `updateChatSettings`: Updates the chat settings. #### Example ```jsx import { useChatInteract } from '@chainlit/react-client'; const InteractionComponent = () => { const { sendMessage, replyMessage } = useChatInteract(); const handleSendMessage = () => { const message = { output: 'Hello, World!', id: 'message-id' }; sendMessage(message); }; const handleReplyMessage = () => { const message = { output: 'Replying to your message', id: 'reply-id' }; replyMessage(message); }; // Render your interaction component return (

); }; ``` --- ### Context7 (`docs/context7.md`) # Context7 Library IDs Pre-resolved library IDs for [Context7 MCP](https://context7.com). Use these when looking up documentation via the Context7 MCP `query-docs` tool. ## Language | Library/Framework | Context7 Library ID | Notes | | ----------------- | ------------------------ | ----------------------------------- | | Python 3.13 | /websites/python_3_13 | Standard library, language features | | TypeScript | /websites/typescriptlang | Type system, compiler options | ## Backend | Library/Framework | Context7 Library ID | Notes | | ----------------- | ------------------------------- | ------------------------------------------ | | Pydantic | /websites/pydantic_dev | Models, validation, serialization | | FastAPI | /websites/fastapi_tiangolo | Web framework, async endpoints | | HTTPX | /encode/httpx | Async HTTP client (core dependency) | | python-socketio | /miguelgrinberg/python-socketio | SocketIO server — core real-time transport | ## LLM integrations | Library/Framework | Context7 Library ID | Notes | | -------------------- | ----------------------------------------------- | ---------------------------------- | | MCP Python SDK | /modelcontextprotocol/python-sdk | Official MCP SDK (core dependency) | | OpenAI Python | /openai/openai-python | OpenAI API client | | Anthropic Python | /anthropics/anthropic-sdk-python | Anthropic API client | | LangChain | /websites/langchain_oss_python_langchain | LLM orchestration, chains, agents | | LlamaIndex | /websites/developers_llamaindex_ai_python | RAG / LLM data framework | | Semantic Kernel | /microsoft/semantic-kernel | Microsoft AI orchestration SDK | | Semantic Kernel docs | /websites/learn_microsoft_en-us_semantic-kernel | Official Microsoft docs | | MistralAI | /mistralai/client-python | MistralAI API client | ## Persistence | Library/Framework | Context7 Library ID | Notes | | -------------------- | ---------------------------------------------- | ------------------------------ | | SQLAlchemy | /websites/sqlalchemy_en_20 | ORM for PostgreSQL/SQLite | | asyncpg | /websites/magicstack_github_io_asyncpg_current | Async PostgreSQL driver | | boto3 | /boto/boto3 | AWS SDK — DynamoDB + S3 | | Azure SDK | /azure/azure-sdk-for-python | Azure SDK for Python | | Azure Storage | /websites/learn_microsoft_en-us_azure_storage | Azure Blob Storage + Data Lake | | Google Cloud Storage | /googleapis/python-storage | GCS persistence | ## Platform integrations | Library/Framework | Context7 Library ID | Notes | | ----------------- | ------------------------- | ----------------------------------- | | Slack Bolt | /slackapi/bolt-python | Slack app framework | | Discord | /llmstxt/discord_llms_txt | Discord bot API | | pandas | /websites/pandas_pydata | Data analysis (optional dependency) | ## Frontend — core | Library/Framework | Context7 Library ID | Notes | | ----------------- | ---------------------------- | ------------------------- | | React | /websites/react_dev | Core UI library | | React Router | /websites/reactrouter_6_30_3 | Client-side routing (v6) | | Vite | /websites/vite_dev | Build tool and dev server | ## Frontend — UI | Library/Framework | Context7 Library ID | Notes | | ----------------- | ----------------------------- | -------------------------------- | | Tailwind CSS | /websites/v3_tailwindcss | Utility-first CSS framework (v3) | | Radix UI | /websites/radix-ui_primitives | Unstyled UI primitives | | lucide-react | /websites/lucide_dev_guide | Icon library | ## Frontend — state & data | Library/Framework | Context7 Library ID | Notes | | ----------------- | --------------------------------- | --------------------------- | | Zustand | /websites/zustand_pmnd_rs | For future Recoil migration | | SWR | /vercel/swr-site | Data fetching hooks | | react-hook-form | /websites/react-hook-form | Form state management | | Zod | /llmstxt/zod_dev_llms_txt | Schema validation | | socket.io-client | /websites/socket_io_v4_client-api | WebSocket client | ## Frontend — rendering | Library/Framework | Context7 Library ID | Notes | | ----------------- | ------------------------- | ------------------------------- | | react-markdown | /remarkjs/react-markdown | Markdown renderer for React | | remark | /remarkjs/remark | Markdown processor | | react-remark | /remarkjs/react-remark | React hooks for remark | | remark-gfm | /remarkjs/remark-gfm | GitHub Flavored Markdown plugin | | remark-math | /remarkjs/remark-math | Math syntax plugin | | highlight.js | /highlightjs/highlight.js | Syntax highlighting | | Plotly.js | /plotly/plotly.js | Charting library | | react-plotly.js | /plotly/react-plotly.js | React wrapper for Plotly | ## Frontend — i18n | Library/Framework | Context7 Library ID | Notes | | ----------------- | ------------------------------ | ------------------------------ | | i18next | /llmstxt/i18next_llms-full_txt | Internationalization framework | | react-i18next | /i18next/react-i18next | React bindings for i18next | ## Testing | Library/Framework | Context7 Library ID | Notes | | ----------------- | --------------------------------- | --------------------- | | pytest | /websites/pytest_en_stable | Python test framework | | Cypress | /cypress-io/cypress-documentation | E2E testing framework | ## Lint & format | Library/Framework | Context7 Library ID | Notes | | ----------------- | --------------------- | -------------- | | ESLint | /websites/eslint | JS/TS linter | | Prettier | /websites/prettier_io | Code formatter | ## Infra | Library/Framework | Context7 Library ID | Notes | | ----------------- | --------------------------- | --------------- | | GitHub Actions | /websites/github_en_actions | CI/CD workflows | --- ### Security Advisory 2026 Mcp (`docs/security-advisory-2026-mcp.md`) # Security Advisory: MCP Endpoint Vulnerabilities **Advisory ID**: SPL-2026-001 / SPL-2026-002 **Severity**: Critical (SPL-2026-001, CVSS v3.1: 9.8) / High (SPL-2026-002, CVSS v3.1: 7.2) **Affected versions**: v2.4.0rc0 – v2.11.x (all versions with `features.mcp.enabled = true`) **Fixed in**: v2.12.0 **Reported by**: SPL Security (vipin@spl.team, stephen@spl.team), 2026-04-08 --- ## Summary Two vulnerabilities were identified in Chainlit's `/mcp` endpoint, which handles Model Context Protocol connectivity. Both require `features.mcp.enabled = true` (disabled by default since v2.7.0) to be exploitable. | ID | Title | CVSS v3.1 | Severity | | ------------ | ---------------------------------- | --------- | -------- | | SPL-2026-001 | Command Injection via MCP stdio | 9.8 | Critical | | SPL-2026-002 | SSRF via MCP streamable-http / SSE | 7.2 | High | --- ## SPL-2026-001 — Command Injection via MCP stdio ### Description The `POST /mcp` endpoint accepted a user-supplied `fullCommand` string when `clientType` was `"stdio"`. This string was validated only by checking the executable name against a configurable allowlist (`allowed_executables`) — arguments were passed through unchecked. Because `npx` (the default allowed executable) supports `-c` for arbitrary shell execution, an attacker could send: ```json { "sessionId": "", "clientType": "stdio", "fullCommand": "npx -y -c 'id > /tmp/pwned'" } ``` The server spawned the subprocess before the MCP handshake completed, so the shell command executed even though the MCP connection subsequently failed. This gave an unauthenticated attacker full code execution on the host running Chainlit. **Root cause**: The design placed subprocess command construction in client-controlled input. No argument-level filtering can safely sandbox this because the attacker controls the full argument list. ### Impact An unauthenticated remote attacker can execute arbitrary shell commands on the Chainlit server with the privileges of the Chainlit process. This allows reading and writing files, exfiltrating secrets, installing backdoors, and pivoting into internal networks. ### Affected configuration Any Chainlit deployment with: ```toml [features.mcp] enabled = true ``` MCP is disabled by default (`enabled = false`) since v2.7.0. --- ## SPL-2026-002 — SSRF via MCP streamable-http / SSE ### Description The `POST /mcp` endpoint accepted arbitrary `url` and `headers` from the client when `clientType` was `"sse"` or `"streamable-http"`. The URL was passed directly to the MCP SDK's HTTP client with no scheme check, no hostname validation, and no allowlist. The attacker also controlled all HTTP headers, enabling header injection attacks. An attacker could force the Chainlit server to make outbound HTTP requests to internal services (cloud metadata endpoints, internal APIs, databases) and forge sensitive headers (`Authorization`, `Cookie`, `X-Internal-Secret`) in those requests: ```json { "sessionId": "", "clientType": "streamable-http", "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials/", "headers": { "Authorization": "Bearer attacker-controlled-token" } } ``` This is a blind SSRF — response bodies are consumed by the MCP client and not returned to the attacker — but it enables service discovery, port scanning, metadata endpoint probing, and side-effect attacks via header injection. ### Impact An unauthenticated remote attacker can cause the Chainlit server to make arbitrary outbound HTTP requests to internal network hosts, forge HTTP headers on those requests, and probe cloud instance metadata services. --- ## Fix ### SPL-2026-001 (Critical) — Architectural fix The `fullCommand` field has been **removed from the client request entirely**. stdio MCP servers are now defined exclusively in server-side configuration (`.chainlit/config.toml`). The client sends only a `name` to activate a pre-configured server: **Before (v2.11.x, vulnerable):** ```json { "sessionId": "...", "clientType": "stdio", "fullCommand": "npx -y @mcp/github" } ``` **After (v2.12.0, fixed):** ```toml # .chainlit/config.toml (developer-controlled) [[features.mcp.servers]] name = "github" type = "stdio" command = "npx -y @modelcontextprotocol/server-github" ``` ```json { "sessionId": "...", "name": "github" } ``` The server looks up the command from its own config and spawns the subprocess. The client cannot influence the command string in any way. ### SPL-2026-002 (High) — Defence-in-depth improvements User-provided SSE/HTTP connections now require an explicit opt-in (`user_servers.enabled = true`) and an URL allowlist. Additionally: - URL scheme enforced to `http`/`https` only - URL allowlist uses parsed-component comparison (prevents subdomain/userinfo bypass) - Path prefix matching normalised to prevent sibling-path bypass (e.g. `/v1-evil` no longer matches an allowlist entry of `/v1`) - Dangerous HTTP headers (`Cookie`, `Host`, `X-Forwarded-*`, `Proxy-Authorization`, etc.) are stripped before forwarding - **HTTP redirects are not followed, for developer-configured ("named") servers as well as user-provided ones.** The MCP Python SDK hardcodes `follow_redirects=True` on the httpx client it builds internally, which means only the _first_ hop of a connection would ever be checked against our destination allowlist (user-provided servers) or origin pin (named servers) — a permitted server could 302 the connection anywhere. httpx forwards every request header except `Authorization` and `Cookie` to a redirect target, so a configured API key carried in a custom header could leak to the redirect destination. `mcp.py`'s `make_mcp_http_client_factory` overrides this with `follow_redirects=False` on the client it hands to both transports, and re-validates every outgoing request (not just the initial URL) against the same `check_destination` hook. That last part also closes a related gap: the SSE transport takes its POST target from the server's own `endpoint` event at runtime, and the SDK accepts any same-origin value for it — including one outside the path subtree an allowlist entry granted. That a configured server's own runtime instructions can move its destination this way is the reason named servers get the same redirect and destination-recheck treatment as user-provided ones: the trust boundary is identical, so hardening only one side would have been inconsistent. Deployments that relied on a redirect to reach their real MCP endpoint should configure the final `https://` URL directly. **Recommended configuration (opt-in user servers):** ```toml [features.mcp.user_servers] enabled = true allowed_urls = ["https://mcp.example.com"] # only permit specific origins ``` --- ## Mitigation for users who cannot upgrade immediately If upgrading to v2.12.0 is not immediately possible: 1. **Disable MCP entirely** — set `features.mcp.enabled = false` in your config (this is the default). This fully prevents exploitation of both vulnerabilities. 2. **Restrict network access** — place the Chainlit server behind a firewall that prevents outbound connections to internal networks and cloud metadata endpoints. 3. **Enable authentication** — configure `@cl.password_auth_callback`, `@cl.header_auth_callback`, or OAuth so that the `/mcp` endpoint requires a valid user session. Anonymous access significantly lowers the bar for exploitation. --- ## Credit Reported by Vipin and Stephen at SPL Security (security@spl.team) under coordinated disclosure. The report included working proof-of-concept exploits for both vulnerabilities tested against Chainlit v2.11.0. We thank SPL Security for the thorough, responsibly disclosed report. --- ## Timeline | Date | Event | | ---------- | ---------------------------------------- | | 2026-04-08 | Report received from SPL Security | | 2026-04-08 | Vulnerabilities confirmed by maintainers | | 2026-04-xx | Fix merged (this PR) | | 2026-xx-xx | v2.12.0 released | | 2026-xx-xx | Advisory published | --- ### Plans 2026 03 31 Eslint V9 Migration (`docs/plans/2026-03-31-eslint-v9-migration.md`) # ESLint v9 Flat Config Migration + lint-staged Unification > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Migrate ESLint from v8 (`.eslintrc`) to v9 (flat config) so that `eslint` with no args defaults to `.` (all files), while explicit file args override this — enabling lint-staged to pass staged files via `pnpm --filter` without linting the entire package. **Architecture:** Replace the JSON `.eslintrc` + `.eslintignore` + `cypress/.eslintrc` with a single `eslint.config.mjs` at the repo root. Update all package `lint` scripts to bare `eslint` (no `--ext`, no directory). Update `lint-staged.config.js` to use package-scoped globs with `pnpm --filter` for ESLint and type-check. **Tech Stack:** ESLint 9, typescript-eslint (unified package), @eslint/js, eslint-plugin-cypress 6, eslint-plugin-chai-friendly **Key behavior (verified empirically on this repo):** - ESLint v9 flat config: `eslint` (no args) = lints `.` (current directory) - ESLint v9 flat config: `eslint file1.ts file2.ts` = lints **only** those files - ESLint v8: no such behavior exists (no args = 0 files, silent exit 0) --- ## File Map | Action | File | Responsibility | | ------ | -------------------------------- | ------------------------------------------------------------------------------ | | Create | `eslint.config.mjs` | Single flat config replacing `.eslintrc`, `.eslintignore`, `cypress/.eslintrc` | | Delete | `.eslintrc` | Replaced by `eslint.config.mjs` | | Delete | `.eslintignore` | Merged into `ignores` array in `eslint.config.mjs` | | Delete | `cypress/.eslintrc` | Merged into `eslint.config.mjs` with `files: ['cypress/**/*.ts']` | | Modify | `package.json` | Update ESLint deps | | Modify | `frontend/package.json` | Remove `--ext` and `./src` from lint script | | Modify | `libs/react-client/package.json` | Remove `--ext` and `./src` from lint script | | Modify | `libs/copilot/package.json` | Remove `--ext` and `./src` from lint script | | Modify | `lint-staged.config.js` | Package-scoped globs with `pnpm --filter` | --- ## Task 1: Update Dependencies **Files:** - Modify: `package.json` (devDependencies) - **Step 1: Remove old ESLint packages and add new ones** ```bash pnpm remove @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint eslint-plugin-cypress ``` - **Step 2: Install ESLint v9 and new packages** ```bash pnpm add -Dw eslint@^9 @eslint/js typescript-eslint eslint-plugin-cypress@^6 ``` > `eslint-plugin-chai-friendly@^1.1.1` stays — its peer dep is `eslint>=3.0.0` and it exports `configs.recommendedFlat` (verified at runtime). - **Step 3: Verify installation** ```bash npx eslint --version ``` Expected: `v9.x.x` - **Step 4: Commit** ```bash git add package.json pnpm-lock.yaml git commit -m "chore: upgrade eslint to v9, add typescript-eslint unified package" ``` --- ## Task 2: Create Flat Config **Files:** - Create: `eslint.config.mjs` This replaces three files: `.eslintrc`, `.eslintignore`, `cypress/.eslintrc`. - **Step 1: Create `eslint.config.mjs`** ```js import eslint from '@eslint/js'; import chaiFriendly from 'eslint-plugin-chai-friendly'; import cypressPlugin from 'eslint-plugin-cypress/flat'; import tseslint from 'typescript-eslint'; export default tseslint.config( // Global ignores (replaces .eslintignore + ignorePatterns) { ignores: ['**/node_modules/', '**/dist/', '**/*.jsx'] }, // Base configs (replaces "extends" in .eslintrc) eslint.configs.recommended, ...tseslint.configs.recommended, // Project rules (replaces "rules" in .eslintrc) { linterOptions: { reportUnusedDisableDirectives: true }, rules: { '@typescript-eslint/no-non-null-assertion': 'off', '@typescript-eslint/no-explicit-any': 'off', 'no-unused-vars': 'off', '@typescript-eslint/no-unused-vars': [ 'error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_', ignoreRestSiblings: true } ] } }, // Cypress overrides (replaces cypress/.eslintrc) { files: ['cypress/**/*.ts'], ...cypressPlugin.configs.recommended, plugins: { 'chai-friendly': chaiFriendly }, rules: { ...chaiFriendly.configs.recommendedFlat.rules } } ); ``` > **Why `.mjs`:** Root `package.json` has no `"type": "module"`, so ESM requires the `.mjs` extension. > > **What's gone:** > > - `"root": true` — flat config doesn't cascade from parent dirs > - `"parser"` — `tseslint.configs.recommended` sets the parser automatically > - `--ext .ts,.tsx` — flat config uses `files` patterns in config objects > - `.eslintignore` — replaced by `ignores` array > - `cypress/.eslintrc` — merged with `files: ['cypress/**/*.ts']` - **Step 2: Verify the config loads** ```bash npx eslint --print-config frontend/src/App.tsx ``` Expected: JSON output showing merged config with `@typescript-eslint/*` rules. - **Step 3: Commit** ```bash git add eslint.config.mjs git commit -m "chore: add eslint v9 flat config" ``` --- ## Task 3: Delete Old Config Files **Files:** - Delete: `.eslintrc` - Delete: `.eslintignore` - Delete: `cypress/.eslintrc` - **Step 1: Delete the old files** ```bash rm .eslintrc .eslintignore cypress/.eslintrc ``` - **Step 2: Verify ESLint still works with flat config only** ```bash npx eslint frontend/src/App.tsx ``` Expected: no errors (or only pre-existing lint errors, not config errors). - **Step 3: Commit** ```bash git add .eslintrc .eslintignore cypress/.eslintrc git commit -m "chore: remove legacy eslintrc config files" ``` --- ## Task 4: Update Package Lint Scripts **Files:** - Modify: `frontend/package.json:10` — `"lint"` script - Modify: `libs/react-client/package.json:9` — `"lint"` script - Modify: `libs/copilot/package.json:10` — `"lint"` script In flat config, `eslint` with no args defaults to `.` and file type matching is handled by config objects (no `--ext` needed). - **Step 1: Update frontend lint script** In `frontend/package.json`, change: ```diff - "lint": "eslint ./src --ext .ts,.tsx", + "lint": "eslint", ``` - **Step 2: Update react-client lint script** In `libs/react-client/package.json`, change: ```diff - "lint": "eslint ./src --ext .ts,.tsx", + "lint": "eslint", ``` - **Step 3: Update copilot lint script** In `libs/copilot/package.json`, change: ```diff - "lint": "eslint ./src --ext .ts,.tsx", + "lint": "eslint", ``` - **Step 4: Verify each package lints correctly** ```bash pnpm --filter @chainlit/app lint pnpm --filter @chainlit/react-client lint pnpm --filter @chainlit/copilot lint ``` Expected: each lints its own directory (`.` = package root). No config errors. > **Note:** This now also lints files outside `src/` (e.g. `vite.config.ts`, test files, storybook files). This is intentional and improves coverage. If any new lint errors surface in those files, fix them before proceeding. - **Step 5: Verify root lint script still works** ```bash pnpm lint ``` Expected: runs all three packages' lint in parallel, same as before. - **Step 6: Commit** ```bash git add frontend/package.json libs/react-client/package.json libs/copilot/package.json git commit -m "chore: simplify package lint scripts for eslint v9 flat config" ``` --- ## Task 5: Update lint-staged Config **Files:** - Modify: `lint-staged.config.js` This is the payoff: package-scoped globs with `pnpm --filter` for ESLint. Prettier stays as direct invocation (it already uses the root `.prettierrc` and lint-staged passes staged files directly). - **Step 1: Replace `lint-staged.config.js` contents** ```js export default { // ── Frontend ────────────────────────────────────── 'frontend/**/*.{ts,tsx}': [ 'pnpm --filter @chainlit/app lint -- --fix', 'prettier --write', () => 'pnpm --filter @chainlit/app type-check' ], // ── React Client ────────────────────────────────── 'libs/react-client/**/*.{ts,tsx}': [ 'pnpm --filter @chainlit/react-client lint -- --fix', 'prettier --write', () => 'pnpm --filter @chainlit/react-client type-check' ], // ── Copilot ─────────────────────────────────────── 'libs/copilot/**/*.{ts,tsx}': [ 'pnpm --filter @chainlit/copilot lint -- --fix', 'prettier --write', () => 'pnpm --filter @chainlit/copilot type-check' ], // ── Cypress (not a workspace package) ───────────── 'cypress/**/*.ts': ['eslint --fix', 'prettier --write'], // ── Root config files ───────────────────────────── '*.{js,cjs,mjs}': ['eslint --fix', 'prettier --write'], // ── Python ──────────────────────────────────────── 'backend/**/*.py': [ 'uv run ruff check', 'uv run ruff format --check', () => 'uv run dmypy run -- backend/' ], // ── GitHub Actions ──────────────────────────────── '.github/workflows/**': ['actionlint'] }; ``` > **How `pnpm --filter @chainlit/app lint -- --fix` works with lint-staged:** > > 1. lint-staged matches staged files against the glob (e.g. `frontend/**/*.{ts,tsx}`) > 2. For string commands, lint-staged appends matched file paths as arguments > 3. Command becomes: `pnpm --filter @chainlit/app lint -- --fix /abs/path/to/file1.tsx /abs/path/to/file2.tsx` > 4. pnpm passes everything after `--` to the package's `lint` script > 5. Script expands to: `eslint --fix /abs/path/to/file1.tsx /abs/path/to/file2.tsx` > 6. ESLint v9: explicit file args override the default `.` — lints **only** the staged files > > **Why prettier stays as direct invocation:** Prettier doesn't have a "default to `.`" mode. The root `.prettierrc` is already the single source of config. lint-staged passes staged files directly — no benefit from `pnpm --filter` indirection. > > **Why** `backend/**/*.py` **instead of** `**/*.py`: Scopes Python linting to backend only, consistent with the package-scoped approach for JS/TS. - **Step 2: Verify lint-staged config is valid** ```bash npx lint-staged --debug 2>&1 | head -20 ``` Expected: no syntax/parse errors. - **Step 3: Test with a staged file** ```bash # Stage a minor whitespace change in a frontend file, then: npx lint-staged --verbose ``` Expected: runs `pnpm --filter @chainlit/app lint -- --fix` with only the staged file, NOT the entire package. - **Step 4: Commit** ```bash git add lint-staged.config.js git commit -m "chore: scope lint-staged to packages with pnpm --filter" ``` --- ## Task 6: Fix Lint Errors in Newly Covered Files ESLint now covers files outside `src/` (config files, tests, storybook). Some may have pre-existing lint issues. **Files:** - Varies — depends on what ESLint reports - **Step 1: Run full lint to find new errors** ```bash pnpm lint 2>&1 ``` - **Step 2: Fix any errors** Most likely candidates: - `vite.config.ts` files — may use `require()` or have unused imports - `frontend/tests/*.spec.tsx` — may have unused variables in test helpers - `libs/copilot/.storybook/*.ts` — may have `any` types (but rule is off) - `libs/copilot/stories/*.ts` — storybook conventions Fix each file. If a file genuinely shouldn't be linted (e.g. auto-generated), add it to the `ignores` array in `eslint.config.mjs`. - **Step 3: Verify clean lint** ```bash pnpm lint ``` Expected: exit 0, no errors. - **Step 4: Commit** ```bash git add -A git commit -m "fix: resolve lint errors in newly covered files" ``` --- ## Task 7: Final Verification - **Step 1: Run full CI-equivalent checks** ```bash pnpm lint && pnpm type-check && pnpm --filter @chainlit/app test ``` Expected: all pass. - **Step 2: Test lint-staged end-to-end** Make a trivial change to a file in each package, stage it, and run: ```bash npx lint-staged --verbose ``` Verify: - Frontend file change triggers only `@chainlit/app` lint + type-check - react-client file change triggers only `@chainlit/react-client` lint + type-check - A Python file change triggers only ruff + dmypy - No cross-package lint runs - **Step 3: Commit any remaining changes** ```bash git add -A git commit -m "chore: complete eslint v9 migration and lint-staged unification" ``` --- ## Risk Checklist | Risk | Mitigation | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `eslint-plugin-chai-friendly` doesn't work in flat config | It exports `configs.recommendedFlat` (verified at runtime). If it fails, wrap with `FlatCompat` from `@eslint/eslintrc`. | | `eslint-plugin-cypress` v6 breaking changes | The v6 `/flat` export is documented. The plugin only adds 2 rules (`no-assigning-return-values`, `no-unnecessary-waiting`). Verify they still trigger. | | New lint errors in previously unlinted files | Task 6 handles this. Scope is small: ~10 files outside `src/` across all packages. | | `pnpm --filter` + lint-staged file passing | Verified empirically: lint-staged appends absolute paths, pnpm passes them after `--`, ESLint v9 lints only those files. | --- ### Plans 2026 04 06 Ci Cache P2 React Client Build Cache (`docs/plans/2026-04-06-ci-cache-p2-react-client-build-cache.md`) # CI Cache Optimization P2 Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Build the frontend artifact that CI still duplicates today exactly once per commit and restore it in downstream jobs, cutting repeated `@chainlit/react-client` builds from the `check-frontend` matrix. **Architecture:** On the current `feat/refactor-scripts` branch, P1 is already implemented and P3 has already collapsed the old `prepare`/`validate` split in `e2e-tests`. The original P2 write-up in `docs/research/ci-cache-optimization.md` assumes `pnpm run buildUi` still runs in `tests` and `e2e-tests`, but that is no longer true in the current workflows. The remaining explicit duplicated frontend build is `pnpm --filter @chainlit/react-client build` inside the three-leg `check-frontend` matrix, so this plan seeds `libs/react-client/dist` once in `ci.yaml`, restores it in `check-frontend.yaml`, and leaves `tests`, `e2e-tests`, and backend checks untouched. **Tech Stack:** GitHub Actions reusable workflows, `actions/cache@v5`, pnpm 9, TypeScript 5, tsup ## Assumptions - P1 is already merged on this branch: `e2e-tests.yaml` uses `actions/cache@v5` for the Cypress binary and no longer uses `cypress-io/github-action`. - P3 is already merged on this branch: `e2e-tests.yaml` has a single `prepare` job and no separate `validate` job. - Backward compatibility matters more than theoretical optimality. Do not rename existing top-level CI jobs that branch protection may already depend on. - The cache boundary for this iteration is only `libs/react-client/dist`. Do not broaden scope to `frontend/dist` or `libs/copilot/dist` unless a fresh measurement proves they are still rebuilt in CI. ## Success Criteria - `check-frontend` no longer runs `pnpm --filter @chainlit/react-client build` in each matrix job. - A new cache-seeding job restores or builds `libs/react-client/dist` once per `github.sha`. - `check-frontend` fails fast if the expected cache is missing, instead of silently rebuilding. - `check-backend`, `tests`, and `e2e-tests` keep their current behavior. - A second CI run for the same commit shows a cache hit in the seed job and no rebuild. --- ## File Map | Action | File | Responsibility | | ------ | ---------------------------------------- | ---------------------------------------------------------------------------------- | | Modify | `.github/workflows/ci.yaml` | Add a one-time cache-seeding job and wire existing jobs to depend on it | | Modify | `.github/workflows/check-frontend.yaml` | Restore `libs/react-client/dist` from cache and remove the duplicated inline build | | Modify | `docs/research/ci-cache-optimization.md` | Update P2 notes so the research doc matches the current branch reality | --- ## Task 1: Seed `@chainlit/react-client` Build Cache Once **Files:** - Modify: `.github/workflows/ci.yaml` - [ ] **Step 1: Add a dedicated cache-seeding job** Insert this job above `check-frontend` in `.github/workflows/ci.yaml`: ```yaml build-react-client: name: Build @chainlit/react-client once runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: ./.github/actions/pnpm-node-install name: Install Node, pnpm and dependencies. - name: Cache @chainlit/react-client dist id: react-client-dist uses: actions/cache@v5 with: path: libs/react-client/dist key: react-client-build-${{ github.sha }} - name: Build @chainlit/react-client if: steps.react-client-dist.outputs.cache-hit != 'true' run: pnpm --filter @chainlit/react-client build ``` Why this exact shape: - `github.sha` is the safest cache key for compiled output because it matches the exact source tree used by downstream jobs. - `actions/cache@v5` restores immediately and saves at job completion, so downstream jobs can rely on the cache after `needs: build-react-client`. - `ubuntu-latest` matches the current `check-frontend` runner, so no cross-OS cache settings are needed. - [ ] **Step 2: Wire `check-frontend` and the CI aggregator to the new job** In `.github/workflows/ci.yaml`, change the existing jobs to: ```yaml check-frontend: needs: [build-react-client] uses: ./.github/workflows/check-frontend.yaml secrets: inherit ci: runs-on: ubuntu-slim name: Run CI if: always() needs: [check-backend, build-react-client, check-frontend, tests, e2e-tests] ``` The extra `build-react-client` entry in `ci.needs` is required. Without it, a failed seed job can cause `check-frontend` to be skipped and the final `ci` job would not treat that upstream failure as a hard failure. - [ ] **Step 3: Verify the workflow file still formats cleanly** Run: ```bash pnpm format-check:files .github/workflows/ci.yaml ``` Expected: exit code `0` and no output complaining about YAML formatting. - [ ] **Step 4: Commit** ```bash git add .github/workflows/ci.yaml git commit -m "ci: seed react-client build cache once per commit" ``` --- ## Task 2: Restore the Cache in `check-frontend` **Files:** - Modify: `.github/workflows/check-frontend.yaml` - [ ] **Step 1: Replace the inline build step with cache restore + explicit failure** In `.github/workflows/check-frontend.yaml`, replace: ```yaml - name: Build @chainlit/react-client run: pnpm --filter @chainlit/react-client build ``` with: ```yaml - name: Restore @chainlit/react-client dist id: react-client-dist uses: actions/cache@v5 with: path: libs/react-client/dist key: react-client-build-${{ github.sha }} - name: Fail if @chainlit/react-client dist cache is missing if: steps.react-client-dist.outputs.cache-hit != 'true' run: | echo "❌ Error: expected react-client build cache for ${GITHUB_SHA}" exit 1 ``` Do **not** add a fallback rebuild here. The point of P2 is to prove the seed job is the single source of truth for this build artifact. Silent rebuilds would hide broken cache wiring. - [ ] **Step 2: Keep the matrix commands unchanged** After the cache restore, the job should still run the existing commands exactly as they are today: ```yaml - name: ${{ matrix.name }} run: ${{ matrix.command }} ``` This preserves the existing job names: - `Linting: frontend` - `Formatting: frontend` - `Type checking: frontend` and avoids unnecessary branch-protection churn. - [ ] **Step 3: Run the local smoke checks in the same order CI depends on** Run: ```bash pnpm --filter @chainlit/react-client build pnpm lint pnpm format-check pnpm type-check ``` Expected: - `pnpm --filter @chainlit/react-client build` writes `libs/react-client/dist` - `pnpm lint` passes - `pnpm format-check` passes - `pnpm type-check` passes - [ ] **Step 4: Commit** ```bash git add .github/workflows/check-frontend.yaml git commit -m "ci: restore react-client build output in frontend checks" ``` --- ## Task 3: Update the Research Doc So P2 Is No Longer Stale **Files:** - Modify: `docs/research/ci-cache-optimization.md` - [ ] **Step 1: Rewrite the P2 problem statement to match the current branch** Update the P2 section so it says the following, in substance: ```md ### P2: Build `@chainlit/react-client` once at CI startup, share via cache **Status**: Still useful on `feat/refactor-scripts`, but the scope is narrower than the original draft. **Current reality on this branch**: - `tests.yaml` no longer runs `pnpm run buildUi` - `e2e-tests.yaml` no longer runs `pnpm run buildUi` - `check-frontend.yaml` still runs `pnpm --filter @chainlit/react-client build` once per matrix leg **Approach**: Seed `libs/react-client/dist` once in `ci.yaml` with `actions/cache`, then restore it in `check-frontend.yaml` and fail on cache miss instead of rebuilding. ``` Keep the rest of the research document intact. This is a surgical doc correction, not a fresh rewrite. - [ ] **Step 2: Update the expected impact table** Change the P2 estimate from the old “buildUi in 7 jobs” numbers to the narrower current branch estimate: ```md | Change | Current | After | Saving | | ------------------------------------------------------------ | ---------------------- | ----------- | ----------------------------- | | P2: cache `@chainlit/react-client` build in `check-frontend` | ~20-40s per matrix leg | ~5s restore | ~45-90s cumulative per CI run | ``` Use the final measured numbers from the first successful CI run if they differ materially from this estimate. - [ ] **Step 3: Verify markdown formatting** Run: ```bash pnpm format-check:files docs/research/ci-cache-optimization.md ``` Expected: exit code `0`. - [ ] **Step 4: Commit** ```bash git add docs/research/ci-cache-optimization.md git commit -m "docs: narrow P2 cache optimization scope to current workflows" ``` --- ## Task 4: Verify the New Workflow Behavior in CI **Files:** - No file changes - [ ] **Step 1: Push the branch and wait for the `CI` workflow to finish** Run: ```bash git push ``` Expected: a new `CI` workflow run starts for the current commit. - [ ] **Step 2: Inspect the first run** Verify in the GitHub Actions UI: - `build-react-client` shows either: - cache miss + one `pnpm --filter @chainlit/react-client build`, or - cache hit + skipped build on a rerun of the same commit - each `check-frontend` matrix job restores `react-client-build-${{ github.sha }}` - no `check-frontend` matrix job logs an inline `pnpm --filter @chainlit/react-client build` - [ ] **Step 3: Re-run the same commit once** Use the GitHub Actions UI to re-run the workflow for the same SHA. Expected: - `build-react-client` shows `cache-hit: true` - the build step is skipped - all `check-frontend` matrix jobs still restore the cache and pass - [ ] **Step 4: Record the measured timings in the research doc** If the measured timing differs from the estimate in Task 3, update the numbers in `docs/research/ci-cache-optimization.md` before merging. - [ ] **Step 5: Commit** ```bash git add docs/research/ci-cache-optimization.md git commit -m "docs: record measured P2 CI cache results" ``` --- ## Non-Goals - Do not reintroduce a full `buildUi` job unless fresh evidence shows `tests` or `e2e-tests` need it again. - Do not cache `frontend/dist` or `libs/copilot/dist` in this change. - Do not change `pnpm-node-install` or `uv-python-install`; P2 does not require action-level abstraction. - Do not change publish workflows as part of this task. ## Self-Review **Spec coverage:** This plan covers P2 only and explicitly adapts it to the current branch state after P1 and P3. It does not assume the stale “buildUi in 7 jobs” model from the research draft. **Placeholder scan:** No `TODO`, `TBD`, or “handle appropriately” placeholders remain. Each workflow edit has exact YAML and each verification step has an exact command or a concrete UI check. **Consistency:** The cache key is consistently `react-client-build-${{ github.sha }}` and the cached path is consistently `libs/react-client/dist` in both producer and consumer jobs. --- ### Research Ci Cache Optimization (`docs/research/ci-cache-optimization.md`) # CI Cache Optimization Research > Last CI run analyzed: [#5989](https://github.com/Chainlit/chainlit/actions/runs/24017813922) on `feat/parallel-cypress` (2026-04-06, success, 13m 36s wall clock) ## Timing Findings ### Critical Path The pipeline bottleneck is **Windows E2E shards** (13m 12s worst case). 60% of that time is setup, not tests. ``` e2e-tests / windows-latest-2 (13m 12s) ← CRITICAL PATH ┌─ Install Node/pnpm ──── 1m 57s ─┐ │ Install Cypress ─────── 1m 33s │ │ Install Python/uv ──── 2m 50s │ 7m 49s setup (60%) │ Build UI ────────────── 1m 29s │ └──────────────────────────────────┘ ┌─ Run tests ───────────── 4m 19s ─┐ 4m 19s actual work └──────────────────────────────────┘ ``` ### All Jobs (wall clock) | Job | Total | pnpm install | Cypress | uv sync | Build UI | Tests | | ---------------------- | ---------- | ------------ | ------- | ---------- | -------- | -------- | | lint-backend | 1m 21s | — | — | 11s | — | mypy 58s | | lint-ui | 1m 52s | 30s | — | — | 1m 07s | lint 10s | | pytest (3.10) | 3m 09s | 33s | — | 58s | 1m 07s | 24s | | pytest (3.11) | 3m 04s | 33s | — | 56s | 1m 06s | 23s | | pytest (3.12) | 3m 03s | 30s | — | 53s | 1m 07s | 29s | | **pytest (3.13)** | **5m 45s** | 30s | — | **3m 40s** | 1m 06s | 25s | | e2e ubuntu (avg of 5) | ~5m 50s | ~31s | ~11s | ~55s | ~1m 07s | ~3m | | e2e windows (avg of 5) | ~11m 56s | ~2m 02s | ~1m 30s | ~2m 28s | ~1m 22s | ~3m 50s | ### Anomalies - **pytest (3.13) uv sync: 3m 40s** — vs ~55s for 3.10–3.12. Verified from logs: uv cache save **failed** during this run due to a transient GitHub cache service outage (`"Our services aren't available right now"`). The 3.13 slowness is likely source-building wheels that lack pre-built binaries for Python 3.13. This is a one-time cost that gets cached naturally once the service recovers — not a config issue. - **Windows pnpm install: ~2m** — vs ~30s on Ubuntu. Disk I/O and process spawning overhead. - **uv cache save failed across all jobs** in this run — transient outage, not a config problem. ### Redundant Work `pnpm run buildUi` (builds `libs/react-client` → `libs/copilot` → `frontend`) runs independently in **7 jobs**: - 2 E2E jobs (ubuntu + windows) × ~1m 10s = ~2m 20s - 4 pytest jobs × ~1m 07s = ~4m 28s - 1 lint-ui job × ~1m 07s = ~1m 07s - **Total: ~8 min of cumulative runner time** rebuilding identical, OS-independent output Note: On `feat/refactor-scripts`, the Hatch build hook is already bypassed — `uv-python-install` uses `--no-install-project --no-editable`, and `pnpm run buildUi` is an explicit step. The `lint-backend` workflow does **not** need the build. --- ## Current Cache Configuration | Tool | Action | Cache mechanism | Status | | ------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------- | | pnpm store | `actions/setup-node@v6.3.0` | `cache: 'pnpm'`, `cache-dependency-path: '**/pnpm-lock.yaml'` | ✅ Working (30s installs on Ubuntu) | | uv download cache | `astral-sh/setup-uv@v8.0.0` | `enable-cache: true` | ✅ Working (55s on Ubuntu), ⚠️ cache miss on 3.13 | | Cypress binary | `cypress-io/github-action@v6` (run used v6 despite local file referencing v7.1.9) | Internal (built-in to the action) | ✅ Ubuntu (11s), ⚠️ Windows (90s) | | Python installation | `actions/setup-python@v6.2.0` | Built-in (pre-installed on runners) | ✅ Fast on Ubuntu | | UI build output | — | **Not cached** | ❌ Rebuilt 14× per run | --- ## Research: Recommended Approaches per Tool ### 1. pnpm — `actions/setup-node` and `pnpm/action-setup` **Source**: [actions/setup-node README](https://github.com/actions/setup-node), [pnpm/action-setup README](https://github.com/pnpm/action-setup) **What's recommended**: - `actions/setup-node` with `cache: 'pnpm'` — caches pnpm's content-addressable store. This is **already in use** and is the recommended approach. - `pnpm/action-setup` also offers `cache: true` but using both is redundant. - Docs explicitly recommend committing `pnpm-lock.yaml` and using `--frozen-lockfile` in CI. **What's NOT recommended**: - Caching `node_modules/` directly. pnpm uses hard-linked content-addressable storage; caching `node_modules` breaks this model and can cause integrity issues. **Assessment**: Current config is correct. No change needed for pnpm caching itself. ### 2. Cypress binary — `cypress-io/github-action` **Source**: [cypress-io/github-action README — "Install Cypress only"](https://github.com/cypress-io/github-action#install-cypress-only) **Recommended pattern** (from the README, section "Install Cypress only"): ```yaml - uses: actions/cache@v5 with: path: | ~/.cache/Cypress node_modules key: my-cache-${{ runner.os }}-${{ hashFiles('package-lock.json') }} - run: npm i cypress - uses: cypress-io/github-action@v7 with: install: false ``` **Key observations**: 1. The README shows explicit `actions/cache` for `~/.cache/Cypress` as the recommended approach when splitting install from test execution. 2. The `cypress-io/github-action` has a `cache-key` input for custom cache keys. 3. For pnpm projects, the README shows: install pnpm → setup-node with `cache: 'pnpm'` → let the Cypress action handle installation. **Verified from CI logs (Ubuntu shard 1)**: 1. `pnpm install` (03:46:41–03:47:00) runs Cypress's `postinstall` hook, which **fully installs the binary** in ~9s: ``` cypress@14.5.3 postinstall: Installing Cypress (version: 14.5.3) cypress@14.5.3 postinstall: Done ``` 2. `cypress-io/github-action@v6` with `runTests: false` (03:47:00–03:47:11, ~11s) then runs again. Its only log output: `"Skipping running tests: runTests parameter is false"`. It re-runs the install/verify (redundant) and saves the Cypress binary cache in its post-step. **Conclusion**: The action is **redundant for installation**. Its only value is the **post-step cache save** of `~/.cache/Cypress`. This can be replaced with a plain `actions/cache` step that: 1. Restores `~/.cache/Cypress` BEFORE `pnpm install` (so postinstall skips the download) 2. Saves it after the job completes This follows the "Install Cypress only" pattern from the action's own README. **Paths for Windows**: The `~/.cache/Cypress` path is Linux-only. Windows uses `~/AppData/Local/Cypress/Cache`. Both must be listed in the `actions/cache` path, OR use the `CYPRESS_CACHE_FOLDER` env var to standardize. ### 3. uv — `astral-sh/setup-uv` **Source**: [setup-uv README](https://github.com/astral-sh/setup-uv), [uv GitHub Actions guide](https://github.com/astral-sh/uv/blob/main/docs/guides/integration/github.md), [uv caching concepts](https://github.com/astral-sh/uv/blob/main/docs/concepts/cache.md) **What's recommended**: - `enable-cache: true` — caches uv's download cache (wheels, sdists). **Already in use.** - `cache-python: true` — caches Python installations managed by uv. **Not currently used.** This would help when uv installs Python (vs `actions/setup-python`). - `cache-dependency-glob` — controls cache key. Defaults to `**/uv.lock` etc. Current config uses defaults. - Manual approach: `actions/cache` with `UV_CACHE_DIR` + `uv cache prune --ci` for more control. **What's NOT recommended**: - Caching `.venv/` directly. The uv docs don't mention or recommend this. uv is designed to be fast at resolving+linking from its cache. - Caching pre-built wheels. From the uv docs: _"it's often faster to omit pre-built wheels from the cache (and instead re-download them from the registry on each run)."_ Only source-built wheels benefit from caching. **Verified from CI logs**: The 3.13 outlier coincided with a **transient GitHub cache service outage** (`"Failed to save: Our services aren't available right now"` in the post-step). All pytest jobs in this run failed to save their uv cache. The 3m40s `uv sync` is likely source-building wheels that don't have pre-built binaries for Python 3.13 yet, combined with the cache miss. **Assessment**: `cache-python: true` would NOT help here — it caches the Python installation binary, not package wheels. The uv download cache (`enable-cache: true`, already in use) is the correct mechanism; it just failed to save in this run due to the outage. No config change needed — this resolves on the next successful cache save. **Important from uv docs**: _"it's often faster to omit pre-built wheels from the cache (and instead re-download them from the registry on each run)."_ Only source-built wheels benefit from caching. The current `enable-cache: true` already handles this correctly. ### 4. UI build output — no standard tool **Source**: No specific recommendation from any action. This is a custom optimization. **Standard GitHub Actions patterns**: 1. **`actions/cache`** — Cache build output keyed on source hash. Pros: simple. Cons: 10GB cache limit shared across all branches; large build outputs can evict other caches. 2. **`actions/upload-artifact` + `actions/download-artifact`** — Build once in a dedicated job, share artifacts with downstream jobs. Pros: no cache eviction issues, guaranteed fresh builds. Cons: adds a sequential dependency (build job must complete before shards start), artifact upload/download overhead. **Assessment**: A dedicated build job with artifact sharing is the cleaner pattern for this case (14 consumers, deterministic output). But it changes the dependency graph — E2E and pytest jobs would need to wait for the build job. --- ## Proposed Changes ### P1: Replace `cypress-io/github-action` with `actions/cache` for Cypress binary **Status**: Verified from logs — the action is redundant for installation. **Why `install: false` + `runTests: false` doesn't help**: The action's cache restore happens in its **main step**, which runs AFTER `pnpm-node-install`. By then, `pnpm install` has already triggered Cypress's `postinstall` hook and downloaded the binary. The cache restore is too late. With both flags off, the action is effectively a no-op during the main step — it only saves the cache in its post-step for future runs. The README's [`install: false` pattern](https://github.com/cypress-io/github-action#install-cypress-only) assumes the action is still used to **run tests**. We don't — we use `pnpm test:e2e` with `cypress-split`. **Approach**: Place `actions/cache` **before** `pnpm install` so the Cypress binary is restored before the postinstall hook runs: 1. Add `actions/cache` for Cypress binary dir BEFORE `pnpm-node-install` 2. Remove the `cypress-io/github-action` step entirely 3. Cypress's `postinstall` hook skips download when it finds the binary pre-cached ```yaml # In e2e-tests.yaml, BEFORE pnpm-node-install: - name: Cache Cypress binary uses: actions/cache@v4 with: path: | ~/.cache/Cypress ~/AppData/Local/Cypress/Cache key: cypress-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }} # Then remove the cypress-io/github-action step entirely. ``` **Cypress version**: `package.json` specifies `^14.5.3`, `pnpm-lock.yaml` resolves to `14.5.4`. Cypress is installed by `pnpm install` (postinstall hook) in both the current and proposed flow — no version change. **Expected critical-path saving**: ~1m 30s per Windows shard (eliminates the redundant action step AND speeds up postinstall via cache hit on warm cache). ### P2: Build UI once at CI startup, share via cache **Status**: Primary optimization — eliminates ~1m build per downstream job (×7 jobs). **Problem**: `pnpm run buildUi` runs independently in 7 jobs, producing identical OS-independent output each time. Without a dedicated build job, all parallel jobs miss the cache simultaneously on the first run and all rebuild. **Build command**: `pnpm run buildUi` = `pnpm build:libs && cd frontend && pnpm run build` **Build output directories**: - `libs/react-client/dist/` - `libs/copilot/dist/` - `frontend/dist/` **Approach**: Add a `build-ui` job in `ci.yaml` that builds once and saves to `actions/cache`. Downstream workflows restore from cache and skip the build. **Cache key**: `ui-build-${{ github.sha }}` Using the commit SHA is the simplest correct key. Enumerating source files in `hashFiles()` would be fragile — the build depends on `package.json`, `pnpm-lock.yaml`, `vite.config.*`, `tsconfig.*`, `index.html`, plus all source in `frontend/src/`, `libs/react-client/src/`, `libs/copilot/src/`. Too many inputs to track reliably. The trade-off: `github.sha` rebuilds on every new commit even if only backend files changed. But on cache hit the `build-ui` job is ~15s (restore only), so the wasted work is minimal. `github.run_id` would NOT work — it's unique per run, so the cache would never hit across runs (e.g. retries). ```yaml # ci.yaml jobs: build-ui: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: ./.github/actions/pnpm-node-install - uses: actions/cache@v4 id: ui-cache with: path: | frontend/dist libs/react-client/dist libs/copilot/dist key: ui-build-${{ github.sha }} - name: Build UI if: steps.ui-cache.outputs.cache-hit != 'true' run: pnpm run buildUi pytest: needs: build-ui # wait for build uses: ./.github/workflows/pytest.yaml e2e-tests: needs: build-ui # wait for build uses: ./.github/workflows/e2e-tests.yaml lint-ui: needs: build-ui # wait for build uses: ./.github/workflows/lint-ui.yaml lint-backend: # no build needed — runs in parallel with build-ui uses: ./.github/workflows/lint-backend.yaml ``` Downstream workflows restore from cache and skip `pnpm run buildUi`: ```yaml # In pytest.yaml, e2e-tests.yaml, lint-ui.yaml — replace the buildUi step: - uses: actions/cache@v4 with: path: | frontend/dist libs/react-client/dist libs/copilot/dist key: ui-build-${{ github.sha }} fail-on-cache-miss: true # build-ui already ran, cache must exist ``` **Why cache over artifacts?**: - **Artifacts**: free for public repos (no storage cap), but re-upload every run even when nothing changed. Each run pays upload+download overhead. - **Cache**: 10 GB per repo (shared with pnpm/uv/Cypress caches), but on repeat runs with the same SHA (retries, re-triggered workflows) the `build-ui` job itself becomes ~15s (cache hit, skip build). Build output is ~50-100 MB, well within limits alongside other caches. **Why `build-ui` is still needed**: Without it, all parallel downstream jobs would miss the cache simultaneously on the first run and all build independently. `needs: build-ui` guarantees the cache is populated before they start. **Trade-off**: `build-ui` adds a sequential dependency. On cache miss: ~1m 30s (pnpm install ~30s + build ~1m). On cache hit: ~15s. `lint-backend` runs in parallel and takes ~1m 20s, so `build-ui` doesn't extend the critical path. **Expected saving**: ~1m per downstream job × 7 jobs = **~7 min cumulative runner time**. Critical path saving: ~1m per Windows E2E job (build eliminated, ~5s cache restore). ### P3: Merge `validate` + `prepare` e2e jobs **Approach**: Combine the two trivial `ubuntu-slim` jobs into one to eliminate a job startup cycle. **Expected saving**: ~10-15s. ### ~~P4: Add `cache-python: true` to setup-uv~~ (dropped) **Reason**: Verified from logs that the Python 3.13 outlier was caused by a transient GitHub cache service outage, not a config issue. `cache-python: true` caches the Python installation binary, which is irrelevant — the slowness came from source-building wheels. The existing `enable-cache: true` already caches built wheels correctly. No change needed. --- ## Estimated Impact on Critical Path | Change | Current (win E2E) | After | Saving | | --------------------------------- | ------------------------------------ | ------------------- | ----------- | | P1: Cypress cache + remove action | 1m 33s (action) + ~30s (postinstall) | ~5s | ~2m | | P2: Build UI once + cache | ~1m 22s (build per job) | ~5s (cache restore) | ~1m 17s | | P3: merge validate+prepare | ~15s overhead | 0s | ~15s | | **Cumulative (critical path)** | **13m 12s** | **~9m 40s** | **~3m 32s** | Notes: - P1 and P2 are the most reliable wins. P2 eliminates redundant builds across all 7 consuming jobs (E2E, pytest, lint-ui) with a single approach. - P2's `build-ui` job adds a sequential dependency (~1m 30s on Ubuntu) but `lint-backend` runs in parallel and takes ~1m 20s, so `build-ui` doesn't extend the critical path. - Cumulative runner time saved (not just critical path): ~9m across all 7 jobs that currently build UI. --- ## Discarded Ideas (with reasons) | Idea | Why discarded | Source | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Cache `node_modules/` directly | pnpm uses hard-linked content-addressable storage; caching `node_modules` breaks this model | [pnpm docs](https://pnpm.io/faq#why-is-it-recommended-to-not-use-npm-ci-for-pnpm), [actions/setup-node](https://github.com/actions/setup-node) | | Cache `.venv/` directly | uv docs don't recommend this; uv is designed to resolve+link fast from its cache | [uv caching docs](https://github.com/astral-sh/uv/blob/main/docs/concepts/cache.md) | | `cache-python: true` in setup-uv | Wouldn't help — 3.13 outlier was source-building wheels (not Python install), and was caused by a transient cache service outage | Verified from CI logs | | Cache pre-built wheels | uv docs explicitly say _"it's often faster to omit pre-built wheels from the cache"_ — only source-built wheels benefit | [uv caching docs](https://github.com/astral-sh/uv/blob/main/docs/concepts/cache.md) | --- ### Research Copilot Type Checking (`docs/research/copilot-type-checking.md`) # Copilot Type Checking — Research & Proposed Solutions ## Problem Statement Running `tsc --noemit` in `libs/copilot/` fails because copilot **directly imports source files from `@chainlit/app` (the frontend)**, and those source files rely on path aliases/baseUrl settings defined in the frontend's own `tsconfig.json` — settings that are **not available** when TypeScript runs under copilot's `tsconfig.json`. The goal is to make `pnpm --filter @chainlit/copilot type-check` work correctly with minimal changes to copilot source code and, if possible, `tsconfig.json`. --- ## Architecture Summary ### Monorepo Workspace (pnpm) ``` pnpm-workspace.yaml: - frontend/ → @chainlit/app (private, no exports/main/types) - libs/react-client/ → @chainlit/react-client (published, has main/types → dist/) - libs/copilot/ → @chainlit/copilot (private) ``` ### Dependency Graph ``` @chainlit/copilot ├── @chainlit/app (workspace:^) ← imports SOURCE files └── @chainlit/react-client (workspace:^) ← imports from dist/ (proper library) ``` ### How Copilot Imports from `@chainlit/app` Copilot reaches **directly into frontend source** via deep path imports: ```typescript // libs/copilot/src/chat/body.tsx import Alert from '@chainlit/app/src/components/Alert'; import ChatSettingsModal from '@chainlit/app/src/components/ChatSettings'; import { ErrorBoundary } from '@chainlit/app/src/components/ErrorBoundary'; import { TaskList } from '@chainlit/app/src/components/Tasklist'; import ChatFooter from '@chainlit/app/src/components/chat/Footer'; import MessagesContainer from '@chainlit/app/src/components/chat/MessagesContainer'; import ScrollContainer from '@chainlit/app/src/components/chat/ScrollContainer'; import Translator from '@chainlit/app/src/components/i18n/Translator'; import { useLayoutMaxWidth } from '@chainlit/app/src/hooks/useLayoutMaxWidth'; import { useUpload } from '@chainlit/app/src/hooks/useUpload'; import { IAttachment, attachmentsState } from '@chainlit/app/src/state/chat'; ``` Full list of imported modules across all copilot files (25 import lines, 22 unique paths, 7 files): | Copilot File | Imported from `@chainlit/app/src/...` | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `widget.tsx` | `components/Alert`, `components/ui/button`, `components/ui/popover` | | `components/WelcomeScreen.tsx` | `components/chat/Starters`, `lib/utils` | | `components/Header.tsx` | `components/AudioPresence`, `components/Logo`, `components/header/ChatProfiles`, `components/header/NewChat`, `components/ui/button` | | `components/ElementSideView.tsx` | `components/Elements`, `components/ui/dialog` | | `appWrapper.tsx` | `i18n` | | `app.tsx` | `components/i18n/Translator` | | `chat/body.tsx` | `components/Alert`, `components/ChatSettings`, `components/ErrorBoundary`, `components/Tasklist`, `components/chat/Footer`, `components/chat/MessagesContainer`, `components/chat/ScrollContainer`, `components/i18n/Translator`, `hooks/useLayoutMaxWidth`, `hooks/useUpload`, `state/chat` | ### Import Categories Not just UI components — copilot imports 6 distinct categories: | Category | Count | Imports | | ------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **UI components** | 13 | `Alert`, `AudioPresence`, `ChatSettings`, `Elements`, `ErrorBoundary`, `Logo`, `Tasklist`, `Starters`, `button`, `dialog`, `popover`, `ChatProfiles`, `NewChat` | | **Composite chat views** | 4 | `Footer`, `MessagesContainer`, `ScrollContainer`, `Translator` | | **Hooks** | 2 | `useLayoutMaxWidth`, `useUpload` | | **Recoil state** | 1 | `state/chat` (`IAttachment`, `attachmentsState`) | | **Utilities** | 1 | `lib/utils` (`cn`, `hasMessage`) | | **i18n config** | 1 | `i18n` (`i18nSetupLocalization`) | ### Contrasted with `@chainlit/react-client` (works correctly) `react-client` is a properly published library: - `package.json` has `"main": "dist/index.js"` and `"types": "dist/index.d.ts"` - Built with `tsup`, emits `.d.ts` declarations - Copilot imports from the package root: `import { useConfig } from '@chainlit/react-client'` --- ## How Copilot Is Used Copilot is **NOT a published npm package**. It is a **self-contained IIFE bundle** that gets embedded into the Python backend and served as a drop-in embeddable widget. ### Build & Distribution Flow ``` libs/copilot/ index.tsx ← Vite entry point vite.config.ts ← builds as IIFE format (not ESM/CJS library) ↓ vite build (rollup, inlineDynamicImports: true) dist/ index.js ← 8.5 MB single IIFE bundle (everything inlined) assets/ ← static assets (pdf.worker.min.mjs ~1 MB) ↓ backend/build.py:copy_copilot() backend/chainlit/copilot/dist/ index.js ← copied into the Python package ↓ FastAPI serves at /copilot/* End user loads