Streamlit Development

This skill provides expert guidance for developing Streamlit, an open-source Python library for building interactive data applications and dashboards.

Repository Overview

Streamlit uses a Python backend (Tornado server) and TypeScript/React frontend, communicating via Protocol Buffers over WebSocket.

Key Directory Structure

Development Workflow

Shell & Build Policy

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

2. **Always use `uv run`** for Python commands:

- `uv run streamlit`

- `uv run pytest`

- `uv run ruff`

- `uv run mypy`

3. **Python unit tests**: `uv run pytest` commands are allowed and encouraged

4. **E2E tests**: Never use `uv run pytest` for E2E tests. Use `make run-e2e-test <filename>` instead

Essential Make Commands

**General:**

**Python/Backend:**

**TypeScript/Frontend:**

**E2E Testing:**

**Debugging:**

- Frontend changes hot-reload in seconds

- Backend only reloads for app script changes (not library changes)

- Logs written to `work-tmp/debug/backend.log` and `work-tmp/debug/frontend.log`

- Browser console output appears in frontend log

- App available at http://localhost:3000

Instructions for AI Agents

When Developing Features

1. **Read existing code first** - Check neighboring files for conventions and patterns

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

3. **Run commands from root** - All `make` commands must run from the top-level directory

4. **Main branch is `develop`** - Not `main` or `master`

When Debugging

1. Use `make debug <script.py>` to start both backend and frontend with hot-reload

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

3. Remember that library changes (`lib/streamlit/`) require restarting `make debug`

4. Browser console output is captured in `work-tmp/debug/frontend.log`

When Testing

1. **Python unit tests**: Use `uv run pytest <path>` for specific tests during development

2. **Frontend unit tests**: Use `make frontend-tests` or Vitest directly

3. **E2E tests**: Always use `make run-e2e-test <filename>` (never `uv run pytest`)

4. **Prefer specific tests** over running entire test suite for newly added tests

5. **Type tests**: Use mypy `assert_type` for verifying public API typing

Before Committing

1. Run `make check` to validate all changes on uncommitted files

2. Ensure all formatting, linting, type checking, and unit tests pass

3. If protobuf definitions changed, run `make protobuf`

Common Patterns

Testing Strategy

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. **Type Tests** - Verify public API typing with mypy `assert_type`

Important Notes