Streamlit Development

This skill guides you through contributing to the Streamlit open-source project. Streamlit is a Python library for creating interactive web applications and dashboards focused on data apps and internal tools.

Architecture Overview

Streamlit uses a client-server architecture:

Repository Structure

Understanding the folder organization:

- `streamlit/`: Main Streamlit 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 (pytest)

- `app/`: Streamlit application UI

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

- `connection/`: WebSocket connection handling logic

- `utils/`: Shared utilities

Development Workflow

Command Execution Policy

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

2. **Always use `uv run`** to run any Python command:

- `uv run streamlit`

- `uv run pytest`

- `uv run ruff`

- `uv run mypy`

3. **Python unit tests**: `uv run pytest` commands are allowed for running specific tests

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

Essential Make Commands

Run these 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 app script changes trigger reruns; library changes require restart

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

- Log files persist after exit for analysis

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

- App available at http://localhost:3000

Development Best Practices

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

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

3. **Run from root**: If `make` commands fail, ensure you're in the top-level directory

4. **Debug efficiently**: Use `make debug <script.py>` for hot-reload development at http://localhost:3000

5. **Check before commit**: Run `make check` to verify formatting, linting, types, and tests on uncommitted files

6. **Main branch**: The primary branch is `develop`, not `main`

Testing Strategy

Apply the appropriate testing level:

Common Tasks

Making Code Changes

1. Identify the appropriate location (`lib/` for backend, `frontend/` for UI)

2. Follow existing patterns in neighboring files

3. Run focused tests for your changes

4. Run `make check` before committing

5. Use `make autofix` to resolve formatting/linting issues

Debugging Issues

1. Create a minimal reproduction script

2. Run `make debug reproduction_script.py`

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

4. Make changes and observe hot-reload behavior

5. Add `console.log()` statements - they appear in `frontend.log`

Modifying Protocol Buffers

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

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

3. Update backend and frontend code to use new message structures

4. Test with `make debug` to verify communication

Running Tests

Important Notes