Streamlit Development Assistant
Expert assistant for developing and contributing to the Streamlit open-source project. Streamlit is a Python library for building interactive data applications and dashboards.
Project Architecture
Tech Stack
**Backend**: Python with Tornado web server, pytest for testing**Frontend**: TypeScript, React, Emotion (CSS-in-JS), Vite bundler, Vitest testing**Communication**: Protocol Buffers (protobuf) over WebSocket**License**: Apache 2.0Repository Structure
**Backend (Python) - `lib/` directory:**
`streamlit/` - Main library package`streamlit/elements/` - Backend code for elements and widgets`streamlit/runtime/` - App runtime and execution logic`streamlit/web/` - Web server and CLI implementation`tests/` - Python unit tests using pytest**Frontend (TypeScript) - `frontend/` directory:**
`app/` - Streamlit application UI`lib/` - Shared TypeScript library with elements, widgets, and layouts`connection/` - WebSocket connection handling`utils/` - Shared utilities**Other key directories:**
`proto/streamlit/proto/` - Protobuf definitions for client-server communication`e2e_playwright/` - End-to-end tests using Playwright`scripts/` - Development and CI/CD utility scripts`component-lib/` - Library for building Streamlit custom components`.github/workflows/` - GitHub Actions CI/CD workflows`wiki/` - Development documentationDevelopment Workflow
Essential Commands
**IMPORTANT**: Always run `make` commands from the repository root directory.
**General:**
`make help` - Show all available make commands`make check` - Run all checks (format, lint, types, unit tests) on changed files only - use before committing`make protobuf` - Recompile Protobufs for Python and frontend`make autofix` - Auto-fix linting and formatting errors**Backend (Python):**
`make python-lint` - Lint and check Python formatting (ruff)`make python-tests` - Run all Python unit tests (pytest)`make python-types` - Run Python type checker (mypy & ty)`make python-format` - Format Python files (ruff)**Frontend (TypeScript):**
`make frontend-fast` - Build frontend (vite)`make frontend-dev` - Start frontend dev server with hot-reload at http://localhost:3000`make frontend-lint` - Lint and check frontend formatting (eslint)`make frontend-types` - Run TypeScript type checker (tsc)`make frontend-format` - Format frontend files (eslint)`make frontend-tests` - Run all frontend unit tests (vitest)**E2E Testing (Playwright):**
`make debug-e2e-test st_command_test.py` - Run E2E test in debug mode`make run-e2e-test st_command_test.py` - Run specific E2E testShell Command Policy for AI Agents
**Python Commands:**
Always prefix Python commands with `uv run` (e.g., `uv run streamlit`, `uv run pytest`, `uv run ruff`, `uv run mypy`)For unit tests: `uv run pytest` commands are allowed and encouraged for running specific tests during developmentFor E2E tests: `uv run pytest` targeting `e2e_playwright/` files is BLOCKED - use `make run-e2e-test <filename>` instead**Build Commands:**
Prefer `make` targets for all development tasks (tests, lint, format, builds)Run all `make` commands from the repository root directoryTesting Strategy
Follow this multi-layer testing approach:
1. **Python Unit Tests** - Test internal backend behavior without frontend interaction
2. **Frontend Unit Tests** - Test React components, hooks, and related functionality using Vitest and React Testing Library
3. **E2E Tests** - Test complete application logic end-to-end with Playwright
4. **Type Tests (Python)** - Verify public API typing with mypy `assert_type`
**Best Practice**: When adding new features, run specific tests for newly added functionality instead of the entire test suite.
Development Best Practices
1. **Follow Existing Patterns**: Always check neighboring files in the same directory to understand conventions and coding style
2. **Use work-tmp Directory**: Store temporary files, specs, and scripts in the `work-tmp` directory
3. **Main Branch**: The main development branch is `develop` (not `main`)
4. **Frontend Development**: Hot-reload dev server runs at http://localhost:3000
5. **Command Location**: If a `make` command fails, verify you're running it from the repository root directory
Common Development Tasks
**Starting Development:**
```bash
Check current codebase state before committing
make check
Start frontend dev server with hot-reload
make frontend-dev
```
**Making Changes:**
```bash
After modifying protobuf definitions
make protobuf
Auto-fix linting/formatting issues
make autofix
Run specific Python tests
uv run pytest tests/path/to/test_file.py
Run specific frontend tests
make frontend-tests
```
**Before Submitting PR:**
```bash
Run comprehensive checks
make check
Run type checkers
make python-types
make frontend-types
```
Key Constraints
All Python commands must use `uv run` prefixE2E tests must use `make` commands, not direct `pytest` invocationsAlways work from the repository root directoryFollow the existing code patterns in neighboring filesThe main branch is `develop`, not `main`