Streamlit Development

Expert assistant for developing the Streamlit open-source library - a Python framework for building interactive data apps and dashboards.

Tech Stack

**Backend:** Python, Tornado server, pytest

**Frontend:** TypeScript, React, Emotion (CSS-in-JS), Vite, Vitest

**Communication:** Protocol Buffers over WebSocket

**License:** Apache 2.0

Folder Structure

```

lib/ # Backend code

streamlit/ # Main library package

elements/ # Element and widget backends

runtime/ # App runtime and execution

web/ # Web server and CLI

tests/ # Python unit tests (pytest)

frontend/ # Frontend code

app/ # Streamlit application UI

lib/ # Shared TS library (elements, widgets, layouts)

connection/ # WebSocket handling

utils/ # Shared utilities

proto/streamlit/proto/ # Protobuf definitions

e2e_playwright/ # E2E tests (Playwright)

scripts/ # Dev/CI utilities

component-lib/ # Custom component library

.github/workflows/ # CI/CD workflows

wiki/ # Development documentation

```

Shell & Build Policy

**CRITICAL RULES:**

Use `make` targets for all development tasks

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

Python unit tests: `uv run pytest` is allowed for specific tests during development

E2E tests: **NEVER** use `uv run pytest` directly on `e2e_playwright/` files

- Instead use: `make run-e2e-test <filename>`

Run all make commands from repository root

Key Make Commands

**General:**

`make help` - Show all available commands

`make check` - Run all checks (format, lint, types, unit tests) on changed files only

`make protobuf` - Recompile protobufs for Python and frontend

`make autofix` - Auto-fix linting and formatting errors

**Python Backend:**

`make python-lint` - Lint and check formatting (ruff)

`make python-tests` - Run all Python unit tests

`make python-types` - Run type checker (mypy & ty)

`make python-format` - Format Python files

**TypeScript Frontend:**

`make frontend-fast` - Build frontend (vite)

`make frontend-dev` - Start dev server with hot-reload

`make frontend-lint` - Lint and check formatting (eslint)

`make frontend-types` - Run TypeScript type checker

`make frontend-format` - Format frontend files

`make frontend-tests` - Run frontend unit tests (vitest)

**E2E Testing:**

`make run-e2e-test st_command_test.py` - Run specific E2E test

**Debugging:**

`make debug my_app.py` - Start backend + frontend with hot-reload

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

- Backend hot-reload: Only app script changes trigger rerun

- Library changes (`lib/streamlit/`) require restart

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

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

Development Workflow

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

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

3. **Debug with hot-reload**: `make debug <script.py>` for rapid iteration

4. **Run checks before commit**: `make check` runs format/lint/types/tests on uncommitted files

5. **Main branch**: `develop` (not `main`)

Testing Strategy

**Python Unit Tests:** Test internal behavior without frontend

**Frontend Unit Tests:** Test React components/hooks with Vitest and React Testing Library

**E2E Tests:** Full app testing with Playwright

**Type Tests:** Verify public API typing with mypy `assert_type`

**Best practice:** Run specific tests for new code, not entire suite

Step-by-Step Instructions

When making backend changes:

1. Locate relevant code in `lib/streamlit/`

2. Follow existing patterns in `elements/`, `runtime/`, or `web/`

3. Run specific tests: `uv run pytest lib/tests/path/to/test.py`

4. Check types: `make python-types`

5. Before commit: `make check`

When making frontend changes:

1. Locate relevant code in `frontend/`

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

3. Run specific tests: `make frontend-tests`

4. Check types: `make frontend-types`

5. Before commit: `make check`

When changing protobuf definitions:

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

2. Regenerate: `make protobuf`

3. Update backend and frontend code to match

4. Run tests for affected areas

When debugging issues:

1. Create test script in `work-tmp/debug_issue.py`

2. Run: `make debug work-tmp/debug_issue.py`

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

4. Make changes with hot-reload active

5. For library changes, restart `make debug`

When adding E2E tests:

1. Create test in `e2e_playwright/`

2. Run: `make run-e2e-test <test_filename>.py`

3. Never use `uv run pytest` directly on E2E files

Important Notes

All Python commands must use `uv run` prefix

E2E tests must use `make run-e2e-test` wrapper

The `make debug` command provides the fastest development iteration cycle

Log files in `work-tmp/debug/` are cleared on each run but persist after exit

Browser console.log output appears in frontend.log

Repository uses Apache 2.0 license

Common Pitfalls

Running make commands from wrong directory (must be repo root)

Forgetting `uv run` prefix for Python commands

Using `uv run pytest` on E2E tests instead of make target

Not restarting `make debug` after library code changes

Not running `make check` before committing

Streamlit Development

Streamlit Development

Tech Stack

Folder Structure

Shell & Build Policy

Key Make Commands

Development Workflow

Testing Strategy

Step-by-Step Instructions

When making backend changes:

When making frontend changes:

When changing protobuf definitions:

When debugging issues:

When adding E2E tests:

Important Notes

Common Pitfalls

Reviews (0)