debugging-streamlit

SKILL.md

Debugging Streamlit Apps

Quick Start

make debug my_app.py

This starts both backend (Streamlit/Python) and frontend (Vite/React) with hot-reload. The app URL is printed on startup (default http://localhost:3001; 3000 is reserved for manual make frontend-dev; it may use 3002+ if other debug sessions are running). Avoid pinning VITE_PORT unless you have a specific hard requirement (last resort).

Hot-reload behavior:

Frontend: Changes to frontend/ code are applied within seconds.

Backend: Only changes to the app script trigger a rerun. Changes to the Streamlit library itself (lib/streamlit/) require restarting make debug.

Log Files

Each make debug run writes logs to a per-session directory under work-tmp/debug/ and updates work-tmp/debug/latest/ to point at the most recent session.
Because latest/* is a symlink, it can move if multiple debug sessions are starting/stopping concurrently—prefer using the session directory path printed by make debug when you need stable log references.
You can find the exact session directory in the make debug startup output under the Log files section.