Streamlit Development

Expert assistant for developing [Streamlit](https://github.com/streamlit/streamlit) - an open-source (Apache 2.0) Python library for creating interactive web applications and dashboards with focus on data apps and internal tools.

Tech Stack

Repository Structure

When navigating the codebase:

- `streamlit/` - Main Streamlit library package

- `streamlit/elements/` - Backend code of elements and widgets

- `streamlit/runtime/` - App runtime and execution logic

- `streamlit/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 logic

- `utils/` - Shared utilities

Development Workflow

Shell & Build Policy

**CRITICAL RULES:**

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

2. Always prefix Python commands with `uv run` (e.g., `uv run streamlit`, `uv run pytest`, `uv run ruff`, `uv run mypy`)

3. For Python unit tests: `uv run pytest` commands are allowed during development

4. For E2E tests: **NEVER** use `uv run pytest` on `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):**

**E2E Testing:**

**Debugging:**

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

- Backend hot-reload: Only changes to the app script trigger rerun; changes to `lib/streamlit/` require restart

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

- Log files are cleared on each run but persist after exit

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

- App available at http://localhost:3000

Testing Strategy

Apply the appropriate test type:

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

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

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

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

**Best Practice:** Run specific tests for newly added functionality instead of the entire test suite.

Development Best Practices

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

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

3. **Run from root** - If a `make` command fails, ensure you're running from the repository root

4. **Debug efficiently** - Use `make debug <script.py>` for hot-reload development

5. **Pre-commit checks** - Run `make check` after completing changes to verify formatting, linting, types, and unit tests on uncommitted files

6. **Main branch** - The main branch of this repository is `develop`

Step-by-Step Instructions

When asked to implement a feature or fix a bug:

1. **Understand the request** - Read existing code in relevant areas (`lib/streamlit/` for backend, `frontend/` for UI)

2. **Follow patterns** - Match the coding style and structure of neighboring files

3. **Make changes** - Implement the feature or fix following Streamlit conventions

4. **Recompile protobuf** - If you modified `.proto` files, run `make protobuf`

5. **Test locally** - Use `make debug <test_script.py>` to verify changes with hot-reload

6. **Run specific tests** - Execute relevant unit tests with `uv run pytest <test_file>` or `make run-e2e-test <e2e_file>`

7. **Pre-commit validation** - Run `make check` to ensure all checks pass on changed files

8. **Autofix issues** - If checks fail, run `make autofix` to automatically fix formatting/linting

9. **Re-run checks** - Run `make check` again to confirm all issues are resolved

Common Scenarios

**Adding a new element/widget:**

1. Define protobuf message in `proto/streamlit/proto/`

2. Run `make protobuf`

3. Implement backend in `lib/streamlit/elements/`

4. Implement frontend in `frontend/lib/`

5. Add tests in `tests/` (Python) and `frontend/` (TypeScript)

6. Test with `make debug`

7. Validate with `make check`

**Debugging an issue:**

1. Create a minimal reproduction script

2. Run `make debug <script.py>`

3. Monitor logs in `work-tmp/debug/backend.log` and `work-tmp/debug/frontend.log`

4. Make changes and observe hot-reload behavior

5. Check browser console output in frontend log

**Running tests:**

Important Notes