Streamlit Development

Expert guidance for developing features and components in the Streamlit repository, following established conventions and workflows.

Overview

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

**Tech Stack:**

Folder Structure Reference

- `elements/` - Backend code for elements and widgets

- `runtime/` - App runtime and execution logic

- `web/` - Web server and CLI

- `tests/` - Python unit tests

- `app/` - Streamlit application UI

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

- `connection/` - WebSocket handling

- `utils/` - Shared utilities

Development Workflow

1. Always Use `make` Commands

Run all development tasks through `make` targets from the repository root:

```bash

make help # Show all available commands

make check # Run all checks on changed files before committing

```

2. Python Command Execution

**REQUIRED:** Always prefix Python commands with `uv run`:

```bash

uv run streamlit

uv run pytest

uv run ruff

uv run mypy

```

3. Testing Policy

**Python Unit Tests:**

**E2E Tests:**

**Frontend Unit Tests:**

**Type Tests:**

4. Common Make Commands

**General:**

**Backend (Python):**

**Frontend (TypeScript):**

5. Debugging with Hot-Reload

Start both backend and frontend with hot-reload:

```bash

make debug my_app.py

```

**Behavior:**

- `work-tmp/debug/backend.log` (Python/Streamlit)

- `work-tmp/debug/frontend.log` (Vite/browser console)

For detailed debugging guidance, see `.claude/skills/debugging-streamlit/SKILL.md`

Development Best Practices

1. **Follow Existing Patterns:** Check neighboring files for conventions before implementing features

2. **Work Directory:** Use `work-tmp/` for temporary files, specs, and scripts

3. **Run from Root:** Always execute `make` commands from the repository root directory

4. **Main Branch:** The main development branch is `develop` (not `main`)

5. **Pre-Commit Check:** Run `make check` after completing changes to validate all uncommitted files

6. **Targeted Testing:** Prefer running specific tests for new features rather than entire test suite

Common Workflows

Adding a New Backend Element

1. Create backend code in `lib/streamlit/elements/`

2. Add unit tests in `lib/tests/`

3. Update protobuf definitions if needed: `make protobuf`

4. Run tests: `uv run pytest <test_file>`

5. Verify: `make check`

Adding a New Frontend Component

1. Create component in `frontend/lib/`

2. Add unit tests using Vitest

3. Test with: `make frontend-tests`

4. Format: `make frontend-format`

5. Type check: `make frontend-types`

6. Verify: `make check`

Testing End-to-End Flow

1. Create test in `e2e_playwright/`

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

3. Debug if needed: `make debug <test_app>.py`

Before Committing

```bash

make check # Validates format, lint, types, unit tests on changed files

```

Troubleshooting

Notes