Streamlit Development

Expert guidance for contributing to the Streamlit open-source project. Streamlit is a Python library for creating interactive web applications and dashboards, focusing on data apps and internal tools.

Tech Stack Overview

Repository Structure

Navigate the codebase efficiently:

- `elements/` — Backend code for elements and widgets

- `runtime/` — App runtime and execution logic

- `web/` — Web server and CLI implementation

- `tests/` — Python unit tests (pytest)

- `app/` — Streamlit application UI

- `lib/` — Shared TypeScript library (elements, widgets, layouts)

- `connection/` — WebSocket connection handling

- `utils/` — Shared utilities

Development Workflow

Shell & Build Policy

1. **Use `make` targets** for all development tasks (tests, lint, format, builds)

2. **Use `uv run`** for all Python commands:

- `uv run streamlit`

- `uv run pytest`

- `uv run ruff`

- `uv run mypy`

3. **Python unit tests:** `uv run pytest` allowed and encouraged for specific tests

4. **E2E tests:** Do NOT use `uv run pytest` for `e2e_playwright/` files. Use `make run-e2e-test <filename>` instead

Essential Make Commands

Run all commands from the repository root:

#### General

#### Backend (Python)

#### Frontend (TypeScript/React)

#### E2E Testing

#### Debugging

- Frontend hot-reload: Changes to `frontend/` apply within seconds

- Backend hot-reload: Only app script changes trigger reruns. Library changes (`lib/streamlit/`) require restart

- Logs: `work-tmp/debug/backend.log` (Python/Streamlit) and `work-tmp/debug/frontend.log` (Vite/browser console)

- Log files cleared on each run but persist after exit

- Browser console output appears in `work-tmp/debug/frontend.log`

- App available at <http://localhost:3000>

Testing Strategy

Apply the appropriate testing approach:

1. **Python Unit Tests** — Test internal behavior without frontend

2. **Frontend Unit Tests** — Test React components, hooks, and functionality with Vitest and React Testing Library

3. **E2E Tests** — Test complete app logic end-to-end with Playwright

4. **Type Tests** — Verify public API typing with mypy `assert_type`

**Best Practice:** Run specific tests for newly added functionality rather than the entire test suite during development.

Development Guidelines

1. **Follow existing patterns** — Check neighboring files for conventions before implementing new features

2. **Use `work-tmp/`** for temporary files, specs, and scripts

3. **Run from root** — All `make` commands must be executed from the repository's top-level directory

4. **Debug efficiently** — Use `make debug <script.py>` to start both backend and frontend with hot-reload at <http://localhost:3000>

5. **Check before commit** — Run `make check` after completing changes to verify formatting, linting, types, and unit tests on uncommitted files

6. **Main branch** — The main development branch is `develop`, not `main`

Step-by-Step Instructions

Making a Code Change

1. Identify the component type (backend Python in `lib/`, frontend TypeScript in `frontend/`, or protobuf in `proto/`)

2. Check neighboring files for existing patterns and conventions

3. Make your changes following the established patterns

4. If modifying protobuf definitions, run `make protobuf` to recompile

5. Run relevant tests:

- Python: `uv run pytest path/to/test_file.py`

- Frontend: `make frontend-tests`

- E2E: `make run-e2e-test test_file.py`

6. Run `make check` to verify all checks pass on changed files

7. If errors, run `make autofix` to auto-correct formatting/linting issues

8. Commit changes to the `develop` branch

Debugging an Issue

1. Create a minimal reproduction script in `work-tmp/reproduce.py`

2. Run `make debug work-tmp/reproduce.py`

3. Access the app at <http://localhost:3000>

4. Frontend changes hot-reload automatically

5. Backend library changes require restarting `make debug`

6. Check logs:

- Backend: `work-tmp/debug/backend.log`

- Frontend: `work-tmp/debug/frontend.log`

7. Add `console.log()` in frontend code to debug — output appears in `work-tmp/debug/frontend.log`

8. Fix the issue and verify with tests

Adding a New Feature

1. Determine if the feature requires:

- Backend changes (`lib/streamlit/`)

- Frontend changes (`frontend/`)

- New protobuf messages (`proto/`)

2. Follow existing patterns in similar features

3. Implement backend logic first if needed

4. Update or create protobuf definitions if adding new communication

5. Run `make protobuf` to generate code

6. Implement frontend UI/logic

7. Add tests at appropriate levels:

- Python unit tests for backend logic

- Frontend unit tests for React components

- E2E tests for complete user workflows

8. Test interactively with `make debug your_test_app.py`

9. Run `make check` before committing

10. Ensure all tests pass

Important Notes