Streamlit Development Assistant

Expert assistant for developing and contributing to the Streamlit open-source project. Provides guidance on backend (Python/Tornado), frontend (TypeScript/React), testing strategies, build workflows, and project conventions.

What This Skill Does

Instructions

Repository Understanding

When working with the Streamlit repository:

1. **Recognize the tech stack:**

- Backend: Python with Tornado server, pytest for testing

- Frontend: TypeScript, React, Emotion (CSS-in-JS), Vite bundler, Vitest for testing

- Communication: Protocol Buffers over WebSocket

- Main branch: `develop` (not `main`)

2. **Navigate the folder structure:**

- `lib/streamlit/`: Core Python library code

- `lib/streamlit/elements/`: Backend implementations of UI elements and widgets

- `lib/streamlit/runtime/`: App execution and runtime logic

- `frontend/app/`: React application UI

- `frontend/lib/`: Shared TypeScript components and utilities

- `proto/streamlit/proto/`: Protobuf message definitions

- `e2e_playwright/`: End-to-end Playwright tests

- `wiki/`: Developer documentation

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

3. **Follow existing patterns:**

- Always check neighboring files for coding conventions and architectural patterns

- Maintain consistency with existing code style and structure

Build and Development Workflow

Always use `make` commands for development tasks. Run all `make` commands from the repository root.

**Common workflows:**

**Backend (Python) development:**

**Frontend (TypeScript/React) development:**

**E2E Testing (Playwright):**

Shell Command Policy for AI Agents

**IMPORTANT:** Follow these strict rules when generating shell commands:

1. **Always use `uv run` prefix for Python commands:**

- Correct: `uv run streamlit run app.py`

- Correct: `uv run pytest tests/test_foo.py`

- Correct: `uv run ruff check lib/`

- Correct: `uv run mypy lib/streamlit`

2. **Python unit tests allow direct pytest:**

- Allowed: `uv run pytest lib/tests/test_widget.py::test_slider`

- Encouraged for running specific tests during development

3. **E2E tests MUST use make targets (direct pytest blocked):**

- Blocked: `uv run pytest e2e_playwright/st_command_test.py`

- Required: `make run-e2e-test st_command_test.py`

- Required: `make debug-e2e-test st_command_test.py`

4. **Prefer `make` targets for all dev tasks:**

- Use `make python-lint` instead of running ruff directly

- Use `make frontend-dev` instead of running vite directly

- Use `make check` before committing

Testing Strategy

Choose the appropriate testing approach based on what you're changing:

**Python Unit Tests** (`lib/tests/`, run with `make python-tests` or `uv run pytest`):

**Frontend Unit Tests** (`frontend/*/src/**/*.test.ts*`, run with `make frontend-tests`):

**E2E Tests** (`e2e_playwright/`, run with `make run-e2e-test <file>`):

**Python Type Tests**:

**Best practices:**

Common Development Scenarios

**Adding a new UI element/widget:**

1. Define protobuf message in `proto/streamlit/proto/*.proto`

2. Run `make protobuf` to regenerate Python and TypeScript bindings

3. Implement backend in `lib/streamlit/elements/`

4. Implement frontend component in `frontend/lib/src/components/`

5. Write Python unit tests in `lib/tests/`

6. Write frontend unit tests alongside component

7. Add E2E test in `e2e_playwright/` if needed

8. Run `make check` before committing

**Fixing a bug:**

1. Write a failing test that reproduces the bug (unit or E2E)

2. Fix the bug in the appropriate layer (backend or frontend)

3. Verify the test now passes

4. Run `make check` to ensure no regressions

**Updating documentation:**

1. Developer docs go in `wiki/`

2. User-facing docs typically live in a separate docs repository

3. Code comments should explain "why" not "what"

**Working with the frontend dev server:**

1. Run `make frontend-dev` to start hot-reload server at http://localhost:3000

2. Make changes to TypeScript/React files

3. Browser auto-refreshes on save

4. Use browser DevTools for debugging

Troubleshooting

**"Make command failed":**

**"Import errors in Python":**

**"Frontend build errors":**

**"E2E tests won't run":**

Constraints

Examples

**Adding a new slider widget:**

```bash

1. Define protobuf message

Edit proto/streamlit/proto/Slider.proto

2. Regenerate bindings

make protobuf

3. Implement backend

Edit lib/streamlit/elements/slider.py

4. Write backend test

Create lib/tests/streamlit/elements/slider_test.py

uv run pytest lib/tests/streamlit/elements/slider_test.py

5. Implement frontend component

Edit frontend/lib/src/components/widgets/Slider/Slider.tsx

6. Start dev server to test

make frontend-dev

7. Write frontend test

Create frontend/lib/src/components/widgets/Slider/Slider.test.tsx

make frontend-tests

8. Add E2E test

Create e2e_playwright/st_slider_test.py

make run-e2e-test st_slider_test.py

9. Final check before commit

make check

```

**Debugging a failing test:**

```bash

Run specific unit test with verbose output

uv run pytest lib/tests/streamlit/runtime/test_app_session.py::test_session_state -v

Debug E2E test with browser visible

make debug-e2e-test st_session_state_test.py

Check types if test involves type assertions

make python-types

make frontend-types

```

**Fixing linting issues:**

```bash

Auto-fix all linting and formatting issues

make autofix

Or fix specific layers

make python-format

make frontend-format

Verify fixes

make check

```