Streamlit Development Assistant

Expert guidance for developing and contributing to the Streamlit open-source project - a Python library for building interactive data applications.

Overview

Streamlit is an Apache 2.0 licensed Python framework for creating web applications. The codebase uses:

Key Directory Structure

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

- `runtime/` - App execution logic

- `web/` - Web server and CLI

- `app/` - Main Streamlit UI application

- `lib/` - Shared components (elements, widgets, layouts)

Development Workflow

1. Environment Setup

All Python commands must use `uv run`:

```bash

uv run streamlit run app.py

uv run pytest tests/

uv run ruff check .

uv run mypy lib/

```

2. Essential Make Commands

**Pre-commit checks:**

```bash

make check # Run all checks on changed files

make autofix # Auto-fix linting/formatting

```

**Backend (Python):**

```bash

make python-lint # Lint with ruff

make python-tests # Run pytest unit tests

make python-types # Type check with mypy

make python-format # Format code

```

**Frontend (TypeScript):**

```bash

make frontend-fast # Build with Vite

make frontend-dev # Start dev server (hot-reload)

make frontend-lint # Lint with eslint

make frontend-types # Type check with tsc

make frontend-tests # Run Vitest tests

```

**Protobuf:**

```bash

make protobuf # Recompile .proto files

```

3. Debugging with Hot-Reload

```bash

make debug my_app.py

```

This starts both backend and frontend with hot-reload at `http://localhost:3000`:

**Logs:**

Logs persist after exit for debugging.

4. Testing Strategy

**Python unit tests (allowed):**

```bash

uv run pytest lib/tests/streamlit/elements/

uv run pytest lib/tests/streamlit/runtime/test_app_session.py

```

**Frontend unit tests:**

```bash

make frontend-tests

```

**E2E tests (use make target only):**

```bash

make run-e2e-test st_command_test.py

```

**Note**: Direct `uv run pytest e2e_playwright/` is blocked by policy. Always use `make run-e2e-test`.

Development Best Practices

Code Organization

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

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

3. **Run make commands from repo root** - not subdirectories

Testing

1. **Python unit tests**: Test internal behavior without frontend

2. **Frontend unit tests**: Test React components with Vitest + React Testing Library

3. **E2E tests**: Test full app logic with Playwright

4. **Type tests**: Verify public API typing with mypy `assert_type`

5. **Run specific tests** during development instead of full suite

Before Committing

```bash

make check # Runs format, lint, types, and unit tests on uncommitted files

```

Main Branch

The primary development branch is `develop` (not `main`).

Common Tasks

Adding a New Element

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

2. Define protobuf message in `proto/streamlit/proto/`

3. Run `make protobuf` to regenerate

4. Add frontend component in `frontend/lib/src/components/elements/`

5. Write Python unit tests

6. Write frontend unit tests

7. Add E2E test if needed

8. Run `make check`

Fixing a Bug

1. Write a failing test that reproduces the bug

2. Fix the bug in appropriate backend or frontend code

3. Verify test passes

4. Run `make check`

5. Test manually with `make debug test_app.py`

Modifying Protobuf Schema

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

2. Run `make protobuf`

3. Update backend code in `lib/streamlit/`

4. Update frontend code in `frontend/`

5. Update tests

6. Run `make check`

Troubleshooting

**"Command not found"**: Ensure you're in the repo root directory

**"Module not found"**: Use `uv run` prefix for all Python commands

**E2E test blocked**: Use `make run-e2e-test <file>` instead of direct pytest

**Frontend not updating**: Check `work-tmp/debug/frontend.log` for build errors

**Backend not restarting**: Library changes require manual restart of `make debug`

Getting Help