Streamlit Development Guide

This skill provides guidance for developing Streamlit data applications, working with the Streamlit open-source codebase.

Overview

Streamlit is an open-source (Apache 2.0) Python library for creating interactive web applications and dashboards focused on data apps and internal tools.

Tech Stack

Repository Structure

Key Directories

- `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 Commands

Shell & Build Policy

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

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

- `uv run streamlit`

- `uv run pytest`

- `uv run ruff`

- `uv run mypy`

3. **Python unit tests:** Use `uv run pytest` commands for running specific tests during development

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

Essential Make Commands

Run these commands from the repository root:

**General:**

**Backend (Python):**

**Frontend (TypeScript):**

**E2E Testing:**

**Debugging:**

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

- Backend hot-reload: Only app script changes trigger rerun; library changes require restart

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

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

- App available at http://localhost:3000

Development Workflow

Step-by-Step Instructions

1. **Before starting development:**

- Ensure you're in the repository root directory

- Check the main branch is `develop`

- Follow existing patterns in neighboring files for conventions

2. **During development:**

- Use `work-tmp` directory for temporary files, specs, and scripts

- Run specific tests for newly added functionality rather than entire test suite

- Use `make debug <script.py>` for debugging with hot-reload

3. **Before committing changes:**

- Run `make check` to verify formatting, linting, type checking, and unit tests on uncommitted files

- Fix any issues identified by the checks

4. **Making code changes:**

- Backend changes: Modify files in `lib/streamlit/`

- Frontend changes: Modify files in `frontend/`

- Protocol changes: Update `proto/streamlit/proto/` and run `make protobuf`

5. **Testing:**

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

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

- **E2E Tests:** Test complete app logic with Playwright

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

Testing Strategy

Common Tasks

Running a Streamlit app

```bash

uv run streamlit run my_app.py

```

Running specific Python tests

```bash

uv run pytest lib/tests/test_specific.py

```

Debugging with hot-reload

```bash

make debug my_app.py

App at http://localhost:3000

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

```

Fixing formatting and linting issues

```bash

make autofix

```

Running all checks before commit

```bash

make check

```

Important Notes