Streamlit Development Assistant

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

Repository Overview

**Project:** [streamlit/streamlit](https://github.com/streamlit/streamlit)

**License:** Apache 2.0

**Purpose:** Open-source Python library for creating interactive web applications with focus on data apps

Technology Stack

Core Directory Structure

- `streamlit/` — Main library package

- `streamlit/elements/` — Element and widget backends

- `streamlit/runtime/` — App runtime and execution

- `streamlit/web/` — Web server and CLI

- `tests/` — Python unit tests (pytest)

- `app/` — Streamlit application UI

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

- `connection/` — WebSocket connection handling

- `utils/` — Shared utilities

Development Commands

All commands should be run from the repository root using `make` targets.

Essential Commands

Backend (Python) Commands

Frontend (TypeScript) Commands

E2E Testing Commands

Debugging Command

- Frontend changes: Hot-reload within seconds

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

- Backend logs: `work-tmp/debug/backend.log`

- Frontend logs: `work-tmp/debug/frontend.log` (includes browser console output)

- App URL: <http://localhost:3000>

Important Development Rules

Shell & Build Policy

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

2. **Always prefix Python commands with `uv run`**:

- `uv run streamlit`

- `uv run pytest`

- `uv run ruff`

- `uv run mypy`

3. **Python unit tests:** Direct `uv run pytest` commands are allowed for specific test files during development

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

Development Best Practices

1. **Follow existing patterns** — Check neighboring files for code conventions

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

3. **Run from root directory** — All `make` commands must be run from repository root

4. **Run `make check` before committing** — Validates formatting, linting, types, and tests on uncommitted files

5. **Main branch is `develop`** — Target pull requests to `develop`, not `main`

Testing Strategy

The repository uses multiple testing approaches:

1. **Python Unit Tests** — Test internal behavior without frontend (pytest)

2. **Frontend Unit Tests** — Test React components and hooks (Vitest + React Testing Library)

3. **E2E Tests** — Test complete app logic (Playwright)

4. **Type Tests** — Verify public API typing (mypy `assert_type`)

**Best Practice:** Run specific test files for newly added tests instead of the entire suite.

Step-by-Step Development Workflow

1. Setting Up for Development

```bash

Navigate to repository root

cd streamlit

Check available commands

make help

```

2. Making Code Changes

For Python changes:

```bash

Format code

make python-format

Check types

make python-types

Run specific tests

uv run pytest lib/tests/path/to/test_file.py

```

For TypeScript/React changes:

```bash

Format code

make frontend-format

Check types

make frontend-types

Run specific tests

make frontend-tests

```

3. Debugging Changes

```bash

Start both frontend and backend with hot-reload

make debug examples/my_test_app.py

Access app at http://localhost:3000

Monitor logs

tail -f work-tmp/debug/backend.log

tail -f work-tmp/debug/frontend.log

```

4. Running E2E Tests

```bash

Run specific E2E test

make run-e2e-test st_command_test.py

```

5. Pre-Commit Validation

```bash

Run all checks on changed files

make check

Auto-fix issues where possible

make autofix

```

6. Rebuilding Protocol Buffers

If you modify `.proto` files:

```bash

make protobuf

```

Common Scenarios

Adding a New Python Element

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

2. Add tests in `lib/tests/streamlit/elements/`

3. Run: `uv run pytest lib/tests/streamlit/elements/test_your_element.py`

4. Run: `make python-types` and `make python-lint`

5. Run: `make check` before committing

Adding a New React Component

1. Create component in `frontend/lib/src/components/`

2. Add styles using Emotion

3. Add tests using Vitest + React Testing Library

4. Run: `make frontend-tests`

5. Run: `make frontend-types` and `make frontend-lint`

6. Test in browser: `make debug test_app.py`

Debugging a Full Feature

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

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

3. Make changes to frontend code → See changes instantly at localhost:3000

4. Make changes to app script → See automatic rerun

5. Make changes to `lib/streamlit/` → Restart `make debug`

6. Check logs in `work-tmp/debug/` if issues occur

Running Tests After Changes

```bash

Quick check of your changes

make check

Specific Python tests

uv run pytest lib/tests/streamlit/runtime/test_caching.py -v

Specific frontend tests

make frontend-tests

Specific E2E test

make run-e2e-test st_sidebar_test.py

```

Key Files and Locations

Troubleshooting

**Make command fails:**

**Frontend changes not appearing:**

**Backend changes not applying:**

**Tests failing:**

**Protocol buffer changes:**

Additional Resources