Skip to main content

Studio Setup Guide

Running Studio​

The Studio provides a visual interface for designing DocTypes and managing your Framework M application.

Single Command​

m studio --port 9999

This starts the Studio server with both the UI and API on a single port.

URL Structure​

The Studio uses a path prefix architecture for clean separation:

  • UI: http://127.0.0.1:9999/studio/ui/

    • Main interface for designing DocTypes
    • All frontend routes are under /studio/ui/*

  • API: http://127.0.0.1:9999/studio/api/

    • Backend endpoints for data operations
    • All API routes are under /studio/api/*

  • Root: http://127.0.0.1:9999/

    • Automatically redirects to /studio/ui/

Development Mode​

For frontend development with hot reload:

Terminal 1 - API Server:

m studio --port 9999

Terminal 2 - Frontend Dev Server:

cd apps/studio/studio_ui
pnpm dev

The Vite dev server runs on http://localhost:5173 with API proxying to port 9999.

Git Noise and Local Builds​

Avoid running pnpm build locally during development.

Running pnpm build updates the static assets in apps/studio/src/framework_m_studio/static/. Since Vite includes hashes in filenames (e.g., index-a1b2c3.js), every build modifies tracked files, creating unnecessary git noise.

Best Practice:

  • Use pnpm dev for frontend development.
  • Rely on CI/CD for release builds. The pipeline automatically rebuilds the UI assets for PyPI packages.
  • Local pnpm build is only necessary to verify production artifacts locally or update the repository snapshot.

Architecture​

Path Prefix Separation​

The Studio implements complete separation between UI and API routes:

/studio/ui/*     → React SPA (HTML pages)
/studio/api/*    → JSON API endpoints
/studio          → Redirects to /studio/ui/

This architecture:

  • ✅ Prevents route collisions
  • ✅ Enables clean URLs (no hash fragments)
  • ✅ Works with single-command deployment
  • ✅ Supports proper Content-Type headers

Static Assets​

Static assets (JS, CSS, images) are served at:

/studio/ui/assets/*

The Vite build process outputs to apps/studio/src/framework_m_studio/static/ which is included in the Python package.

API Endpoints​

Health Check​

curl http://127.0.0.1:9999/studio/api/health

List DocTypes​

curl http://127.0.0.1:9999/studio/api/doctypes

Get DocType​

curl http://127.0.0.1:9999/studio/api/doctype/User

Field Types​

curl http://127.0.0.1:9999/studio/api/field-types

Building for Production​

Build Frontend​

cd apps/studio/studio_ui
pnpm build

This outputs to ../src/framework_m_studio/static/ which is packaged with the Python distribution.

Package Python​

cd apps/studio
uv build

The built wheel includes the static frontend assets.

Troubleshooting​

UI Downloads Instead of Rendering​

If the browser downloads HTML files instead of rendering them, check:

  1. Content-Type Headers: Ensure responses have Content-Type: text/html; charset=utf-8
  2. Route Handlers: Verify return type is Response not union types
  3. Browser Cache: Clear browser cache and hard reload (Ctrl+Shift+R)

If refreshing a page like /studio/ui/doctypes/edit/User gives 404:

  1. Check Route Handler: Ensure /studio/ui/{path:path} wildcard route exists
  2. SPA Fallback: Verify the handler returns index.html for non-file paths
  3. Base Path: Confirm React Router uses basename="/studio/ui"

API Calls Failing​

If API calls return errors:

  1. CORS: Check CORS configuration allows your origin
  2. Path Prefix: Ensure API calls use /studio/api/* prefix
  3. Server Running: Verify m studio is running on the correct port