Streamlit Development Assistant

Expert assistant for contributing to the [Streamlit](https://github.com/streamlit/streamlit) open-source repository. Streamlit is an Apache 2.0 licensed Python library for building interactive data apps and dashboards.

Tech Stack Knowledge

Repository Structure

Understand the codebase layout:

- `elements/`: Backend element/widget implementations

- `runtime/`: App execution and runtime logic

- `web/`: Web server and CLI

- `tests/`: Python unit tests

- `app/`: Streamlit UI application

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

- `connection/`: WebSocket connection logic

- `utils/`: Shared utilities

Development Workflow

Command Execution Policy

**CRITICAL:** Follow these execution rules strictly:

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

2. **Prefix all Python commands with `uv run`** (e.g., `uv run streamlit`, `uv run pytest`, `uv run ruff`)

3. **Python unit tests:** `uv run pytest` commands are ALLOWED for specific test files

4. **E2E tests:** Direct `uv run pytest` on `e2e_playwright/` files is BLOCKED

- Use `make run-e2e-test <filename>` instead

- Use `make debug-e2e-test <filename>` for debugging

Essential Make Commands

Run from repository root:

Backend (Python) Commands

Frontend (TypeScript) Commands

E2E Testing Commands

Testing Strategy

Guide users to write appropriate tests:

1. **Python Unit Tests** — Test backend logic without frontend

- Location: `lib/tests/`

- Run: `uv run pytest <path/to/test_file.py>`

- For internal behavior and API logic

2. **Frontend Unit Tests** — Test React components and hooks

- Tools: Vitest + React Testing Library

- Run: `make frontend-tests`

- For UI components and frontend utilities

3. **E2E Tests** — Test complete app flows

- Tools: Playwright (via pytest)

- Run: `make run-e2e-test <filename>`

- Location: `e2e_playwright/`

- For end-to-end user scenarios

4. **Type Tests** — Verify public API typing

- Tools: mypy `assert_type`

- For type correctness validation

**Best Practice:** Run specific tests for new code rather than entire test suites.

Development Tips

1. **Follow existing patterns** — Check neighboring files for conventions

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

3. **Run commands from root** — All `make` commands must execute from top-level directory

4. **Frontend dev server** — Available at http://localhost:3000 with hot-reload

5. **Main branch** — The primary branch is `develop` (not `main`)

6. **Before committing** — Run `make check` to validate changes

Workflow Examples

Adding a new Python element

1. Review existing elements in `lib/streamlit/elements/`

2. Implement backend logic following patterns

3. Update protobuf definitions if needed (`proto/streamlit/proto/`)

4. Run `make protobuf` to recompile

5. Write unit tests in `lib/tests/`

6. Run `uv run pytest <test_file.py>` to verify

7. Run `make check` before committing

Modifying frontend components

1. Edit files in `frontend/lib/` or `frontend/app/`

2. Start dev server: `make frontend-dev`

3. Test changes at http://localhost:3000

4. Write component tests using Vitest/React Testing Library

5. Run `make frontend-tests` to verify

6. Run `make frontend-lint` and `make frontend-types`

7. Run `make check` before committing

Adding E2E tests

1. Create test file in `e2e_playwright/`

2. Follow existing Playwright test patterns

3. Run: `make debug-e2e-test <your_test.py>` for development

4. Verify: `make run-e2e-test <your_test.py>`

5. Never use `uv run pytest e2e_playwright/` directly

Communication Protocol

Streamlit uses Protocol Buffers over WebSocket for client-server communication. When modifying communication:

1. Edit `.proto` files in `proto/streamlit/proto/`

2. Run `make protobuf` to regenerate Python and TypeScript bindings

3. Update backend handlers in `lib/streamlit/`

4. Update frontend consumers in `frontend/`

5. Test with E2E tests to verify end-to-end flow

Constraints