Mesop

Use this skill to build, debug, and deploy Mesop applications. Mesop is a Python-native UI framework that enables developers to build web apps without writing frontend code (HTML/CSS/JS).

Quick Triage

• Use this skill for pure Python web UIs, especially for AI/ML demos and internal tools.
• Do NOT use this skill if the user specifically requests a different Python framework (Streamlit, Gradio, Solara) unless they are asking for a comparison or migration.
• Do NOT use this skill for general Flask/FastAPI backend development unless it’s specifically about mounting a Mesop app.

Workflow

1. Setup: Install mesop and create main.py.
2. Define Page: Use @me.page(path="/") to define the entry point.
3. Define State: Create a @me.stateclass to hold session state (must be serializable).
4. Create Components: Build the UI tree using me.box, me.text, me.input, etc.
5. Handle Events: Write event handler functions (regular or generator) to update state.
6. Style: Apply styles using me.Style (flexbox/grid) for layout and appearance.
7. Deploy: Deploy to Cloud Run, Docker, or Hugging Face Spaces.

Essential Patterns

Standard Import

Always use the standard alias:

import mesop as me
import mesop.labs as mel # For labs components like chat

State Management

State is session-scoped and must be serializable.

@me.stateclass
class State:
  count: int = 0
  input_value: str = "" # Immutable default
  # items: list[str] = field(default_factory=list) # Mutable default pattern

Accessing State: state = me.state(State) inside components or event handlers.

Event Handlers

• Regular: Run to completion, then update UI.
• Generator: yield to stream UI updates (e.g., loading states, LLM streaming). MUST yield at the end.
• Async: Use async def and await for concurrent operations.

Component Composition

Use with blocks for content components (parents):

with me.box(style=me.Style(display="flex")):
  me.text("Child 1")
  me.button("Child 2")

Key Usage

Use key to identify components for:

• Resetting state (change key to re-render)
• Focus management (me.focus_component)
• Scroll targeting (me.scroll_into_view)
• Reusing event handlers (access e.key)

Common Pitfalls

• Closure Variables: Do NOT rely on closure variables in event handlers; they may be stale. Use key or state instead.
• Input Race Conditions: Avoid setting value on inputs unless necessary. Use on_blur instead of on_input for performance, or track “initial” vs “current” value if bidirectional binding is needed.
• Mutable Defaults: Never use mutable types (list, dict) as default values in @me.stateclass. Use dataclasses.field(default_factory=...).
• Global State: Global variables are shared across ALL users. Use @me.stateclass for per-session state.

Reference Map

• Core Patterns: references/core-patterns.md (State, Events, Streaming, Navigation)
• Components: references/components-reference.md (API reference for all components)
• Styling & Layouts: references/styling-and-layouts.md (CSS-in-Python, Flexbox, Grid, Theming)
• Deployment: references/deployment-and-config.md (Cloud Run, Docker, Config, Security)
• Web Components: references/web-components.md (Custom JS integration, Lit)