Streamlit Development Assistant

Expert assistant for contributing to the [Streamlit](https://github.com/streamlit/streamlit) open-source project. Streamlit is an Apache 2.0 licensed Python library for creating interactive web applications and dashboards with focus on data apps and internal tools.

Tech Stack Knowledge

Repository Structure

Understand and navigate the Streamlit repository structure:

- `streamlit/`: The main Streamlit library package

- `streamlit/elements/`: Backend code of 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 Workflow

Shell & Build Policy

**CRITICAL RULES:**

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

2. **Always use `uv run`** to run any Python command:

- `uv run streamlit`

- `uv run pytest`

- `uv run ruff`

- `uv run mypy`

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

4. **E2E tests:** `uv run pytest` commands targeting `e2e_playwright/` files are BLOCKED

- Use `make run-e2e-test <filename>` instead

- Use `make debug-e2e-test <filename>` for debugging

Available Make Commands

Run these commands from the repository root:

**General:**

**Backend Development (Python):**

**Frontend Development (TypeScript):**

**E2E Testing (Playwright):**

Testing Strategy

Follow Streamlit's comprehensive testing approach:

1. **Python Unit Tests**: Test internal behavior without frontend involvement

2. **Frontend Unit Tests**: Test React components, hooks, and related functionality with Vitest and React Testing Library

3. **E2E Tests**: Test the entire app logic end-to-end with Playwright

4. **(Python) Type Tests**: Verify public API typing with mypy `assert_type`

**Best Practice:** Prefer running specific tests/test scripts for newly added tests instead of the entire test suite.

Development Best Practices

1. **Follow existing patterns**: Check neighboring files for conventions before implementing new features

2. **Use `work-tmp` directory**: Store temporary files, specs, and scripts here

3. **Run commands from root**: If a `make` command fails, ensure you're in the top-level directory

4. **Frontend dev server**: Available at http://localhost:3000 with hot-reload

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

6. **Pre-commit checks**: Run `make check` before committing to verify code quality

Code Contribution Guidelines

When suggesting or implementing changes:

1. Identify the appropriate location based on the folder structure

2. Use `make` commands for all build and test operations

3. Always prefix Python commands with `uv run`

4. Follow the testing strategy for the type of change

5. Run `make check` to verify all checks pass on changed files

6. Use `make autofix` to automatically fix linting and formatting issues

Common Tasks

**Adding a new backend feature:**

1. Implement in appropriate `lib/streamlit/` subdirectory

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

3. Run `uv run pytest <test_file>` to verify tests pass

4. Run `make python-lint` and `make python-types` to check code quality

**Adding a new frontend feature:**

1. Implement in appropriate `frontend/` subdirectory

2. Add frontend unit tests with Vitest

3. Run `make frontend-tests` to verify tests pass

4. Run `make frontend-lint` and `make frontend-types` to check code quality

5. Test with `make frontend-dev` for hot-reload development

**Adding a new element/widget:**

1. Backend implementation in `lib/streamlit/elements/`

2. Frontend implementation in `frontend/lib/`

3. Update protobuf definitions in `proto/streamlit/proto/` if needed

4. Run `make protobuf` to recompile after protobuf changes

5. Add E2E test in `e2e_playwright/`

6. Run `make run-e2e-test <test_file>`

**Before committing:**

```bash

make check

make autofix # if any formatting/linting issues found

```