<h1 align="center">
<a href="https://prompts.chat">
Guidance for AI coding agents working in this repository.
Loading actions...
<a href="https://prompts.chat">
TypeScript and ESLint rules that MUST be followed when creating, modifying, or reviewing any file under apps/frontend/, including .ts, .tsx, .js, and .jsx files. Also apply when discussing frontend linting, type safety, or ESLint configuration.
risks
Guidance for AI coding agents working in this repository.
Before you write code, read docs/agents/PHILOSOPHY.md. Most off-narrative work comes from skipping it.
Langflow is a visual flow builder first. Users drag components onto a canvas, wire them together, and either run the resulting flow in the Playground, deploy it as an API, or expose it as an MCP server. Saved flows are persistent JSON artifacts running in production — backwards compatibility for components is non-negotiable.
The repo is three Python packages and one frontend:
lfx (src/lfx/): the executor core. Component base classes, the graph engine, and built-in components live here. Should not depend on langflow or langflow-base — see docs/agents/ARCHITECTURE.md for the ~14 known violations to fix-not-extend.langflow-base (src/backend/base/langflow/): the platform. FastAPI routes, auth, persistence, alembic, services. May import lfx.langflow: the integration distribution that ships everything together.frontend (src/frontend/): React 19 + TypeScript + Vite + Zustand + @xyflow/react. Talks to the backend over HTTP/WebSocket only.Dependencies flow one way: frontend → langflow → langflow-base → lfx. See docs/agents/ARCHITECTURE.md.
These are extracted from PHILOSOPHY.md. The full file has the rest; these are the ones every change must respect.
name attributes, input/output names, and input types are frozen once shipped. Mark old components legacy=True instead of editing.lfx, not langflow-base.Read the file that matches your task before you write code.
| Topic | File | When to read |
|---|---|---|
| Project story, design tenets | docs/agents/PHILOSOPHY.md | Before any non-trivial change |
| Package boundaries, where code goes, API versioning | docs/agents/ARCHITECTURE.md | Before adding a file or endpoint |
| Component dev: scope, breaking changes, conventions, icons | docs/agents/COMPONENTS.md | Before adding or editing a component |
| User-facing contracts: flow JSON, REST API, MCP, env vars | docs/agents/CONTRACTS.md | Before changing anything user-visible |
| Test patterns, fixtures, mocking policy | docs/agents/TESTING.md | Before writing or changing tests |
| Don't/do rules, "fixes that aren't," before-claiming-done checklist | docs/agents/ANTI-PATTERNS.md | Before claiming work is done |
uv run for Python commands)make init # Install all dependencies + pre-commit hooks
make run_cli # Build and run Langflow (http://localhost:7860)
make run_clic # Clean build and run (use when frontend issues occur)
make backend # FastAPI on port 7860 (terminal 1)
make frontend # Vite dev server on port 3000 (terminal 2)
For component development with dynamic loading:
LFX_DEV=1 make backend # Load all components dynamically
LFX_DEV=mistral,openai make backend # Load only specific modules
make format_backend # Format Python (ruff) — run FIRST before lint
make format_frontend # Format TypeScript (biome)
make format # Both
make lint # mypy type checking
make unit_tests # Backend unit tests (pytest, parallel)
make unit_tests async=false # Sequential
uv run pytest path/to/test.py # Single test file
uv run pytest path/to/test.py::test_name # Single test
make test_frontend # Jest unit tests
make tests_frontend # Playwright e2e tests
# lfx tests specifically — run uv sync inside src/lfx (not src/lfx/src/lfx)
cd src/lfx && uv sync && uv run pytest
# Sub-package tests (langflow-base, lfx) — sync that package's dev group first,
# otherwise dev-only deps like fakeredis stay uninstalled.
uv sync --group dev --package langflow-base
See docs/agents/TESTING.md for fixtures, base classes, and the graph testing pattern.
make alembic-revision message="Description" # Create migration
make alembic-upgrade # Apply migrations
make alembic-downgrade # Rollback one version
Never edit a past migration. Run test_database.py sequentially after any DB change.
make patch v=1.5.0 # Update version across all packages
Pre-commit hooks run ruff and biome automatically on git commit, so manual formatting isn't required. To avoid an extra commit cycle:
make format_backend once before staging — fixes most ruff issues up front.uv run git commit (the uv run ensures pre-commit finds the right Python).make unit_tests locally for faster feedback than CI.Fixes #1234).release-X.Y.Z branch, not main. See CONTRIBUTING.md.Co-Authored-By: Claude trailers.Documentation uses Docusaurus and lives in docs/:
cd docs
yarn install
yarn start # Dev server on port 3000 (3001 if 3000 is in use)