Platform-Aware briefcase dev Command with Editable Installs for Web Development

[JMah007]

Initial Discussion at #2282

What is the problem or limitation you are having?

Currently, briefcase dev is only supported on desktop platforms. For web backend, contributors must rebuild and repackage the entire project into wheels (e.g. `briefcase run web -r -u) even for minor changes. This process introduces significant wait times and slows down the speed of iteration for those developing Toga's web backend or debugging UI issues in the browser.

Describe the solution you'd like

We propose extending briefcase dev to support web development. The solution should:

Core Features

• Extend briefcase dev to be platform-aware and support web applications
• Use editable installs and .pth files instead of rebuilding .whl packages for pure Python modules
• Enable immediate code changes to be reflected in the browser with just a page refresh

Technical Implementation

1. Dedicated Dev Environment: Create a separate development virtual environment that contains only the pure Python modules needed for development
2. Editable Installs: Install the application and pure Python dependencies (like Toga modules) as editable pip installs in the dev venv
3. Dynamic Source Mapping: Use .pth files to reference actual source folders and serve the latest versions directly to the browser via symlinks
4. Static Asset Serving: Serve Toga Python modules as standard .py files to PyScript's in-browser virtual filesystem

Expected Outcome

• Immediate feedback when making code changes (refresh browser instead of rebuild)
• Faster development iteration cycles
• Seamless integration with the existing Briefcase workflow

Describe alternatives you've considered

Alternative 1: File Watching with Auto-Rebuild

• Implement a file watcher that automatically triggers rebuilds when source files change
• Limitation: Still requires the rebuild step, only automates it. Doesn't eliminate the wait time.

Alternative 2: Hybrid Approach with Partial Rebuilds

• Only rebuild changed modules instead of the entire application
• Limitation: Still involves a build step and doesn't provide the immediacy of serving source files directly.

The proposed solution with editable installs and .pth files is preferred because it:

• Leverages existing Python packaging mechanisms
• Provides the fastest possible feedback loop
• Maintains compatibility with the existing Briefcase architecture
• Allows for easy switching between dev and production modes

Additional context

Technical Breakdown

The work can be broken down into two main components:

1. Enable Platform-aware dev commands - Modify the core briefcase dev command to detect and handle web platform differently
2. Local Python file serving - Implement the venv setup, editable installs, and .pth file reading to serve source files to the browser

Note that some implementations here might resolve the issues stated in #1735 proposing a standalone virtual environment for dev mode in order to reduce dependency conflicts.

Future Enhancements

The following features are planned as optional future iterations

1. Third-party dependency handling - Implement support for Pyodide's micropip and WASM-compatible wheels for libraries like numpy/pandas, this covers Web / Add Support for "Pyodide Packages" #1104, and it should be noted that when PEP 783 is finalised, this should be revisited.
2. Hot reload functionality - Build upon the proposed solution to enable automatic browser refresh when code changes are detected, using CLI flags such as --live or --reload

Use Case

This enhancement is particularly valuable for developers working on:

• Toga-based web applications
• PyScript applications using Briefcase
• Any Python web app where frequent UI/logic iteration is required

References

PyScript Filesystem Guide for in-browser virtual filesystem implementation

---

Roadmap of Changes: briefcase dev Support for Web

1. Dev-Mode Command & Venv Management

• Implement briefcase dev web via a WebDevCommand subclass that respects platform and --test mode.
• Auto-create or refresh the isolated .briefcase/dev-web-venv (with the -r flag), using the same editable-install mechanism we'll share with desktop.

2. Unified Dev Environment & Asset Pipeline

• Editable Installs
  • Install all pure-Python requirements in editable mode, generating .pth references.
• Symlink & Serve
  • Parse each .pth file and symlink its source directory into the relevant static root (.briefcase/<app name>/www), alongside an auto-generated index.html and launch a single static HTTP server to expose these assets.

3. Third-Party Package Support (Optional)

• Serve pure-Python wheels over the same static server for micropip.install().
• Optionally detect and micropip.loadPackage() known Pyodide-compatible binary packages, tracking any dynamic-only exceptions.

4. Live-Reload (Optional)

• Add a --live/--reload flag to watch .py source files, re-bundle on change, and trigger an in-browser refresh.

5. Desktop Parity

• Evaluate extending editable install behavior to desktop briefcase dev.

[freakboy3742]

@mEp3ii2 Due to the wonders that is Github UI, I can't assign you to this ticket until you've commented on it

[mEp3ii2]

@mEp3ii2 Due to the wonders that is Github UI, I can't assign you to this ticket until you've commented on it

Reporting for duty

[JMah007]

Web Dev Mode Implementation - Handover Document

Project Overview

This document provides a handover for the implementation of briefcase dev web - a development mode for Briefcase web applications that enables hot-reload functionality without requiring wheel builds. The semester has concluded, and this work is being handed over to future contributors.

Current Status

Completed Work

PR #2419: Make Dev Command Platform Aware - Merged

• Link: Make Dev command platform aware #2419
• Made DevCommand platform-aware to support platform-specific behavior
• Enables web platform to have distinct dev mode implementation
• Foundation for subsequent virtual environment and dev mode work

PR #2420: Virtual Environment Management - Merged

• Link: And Venv Management to Dev Command Web Platform #2420
• Virtual environment infrastructure implemented in base DevCommand
• Support for isolated and non-isolated modes
• Platform-specific venv naming (web uses dev-web)
• StaticWebDevCommand stub exists but raises UnsupportedCommandError

PR #2498: Editable Install Foundation - In Progress (near merge)

• Link: Modify Dev Web Command to Support Editable Installs For Pure Python Requirements  #2498
• Branch: add-editable-install-dependencies
• Editable install logic implemented in DevCommand.install_dev_requirements()
• Detects local vs remote dependencies using _is_local_path()
• Installs local dependencies with pip install -e
• Web platform inherits automatically through inheritance

---

Remaining Implementation

PR 2: .pth File Parsing Utility

This PR establishes the foundation for discovering where editable-installed source code actually lives on disk. When packages are installed with pip install -e, Python creates .pth files in the venv's site-packages directory containing paths to the actual source directories. This parsing utility reads those .pth files and extracts clean filesystem paths that subsequent PRs will use to create symlinks. The parser needs to handle various .pth file formats: simple files that just list directory paths (one per line), and complex files that might include Python code or import statements (which should be ignored for safety). The parsing logic reads each .pth file line-by-line, filters out comments, blank lines, and any executable code, and returns a clean list of absolute source directory paths. These paths are what PR 3 will use to create symlinks, but the parsing itself is completely independent—it's just reading text files and extracting filesystem paths, making it perfect for standalone development and testing with mock .pth files.

Technical Details:

• Location: src/briefcase/platforms/web/static.py - StaticWebDevCommand
• New methods: _parse_pth_file(pth_path), _discover_editable_packages(venv)
• Must filter comments, blank lines, and Python code from .pth files
• Returns dict mapping package names to source paths
• Test with fixture .pth files in various formats

---

PR 3: Symlink Creation & Asset Setup

This PR constructs the dev environment's directory structure by creating symlinks in www/static/ that point directly to the editable-installed source code. The implementation walks through each discovered source path, identifies Python packages within it, and creates symlinks that mirror the package structure (e.g., www/static/toga_web/ → /home/user/projects/toga/web/src/toga_web/). This is the critical piece that enables PyScript to load modules from local source files instead of from pre-built wheels, giving you true hot-reload capability—when you edit source code in your IDE, just refresh the browser to see changes instantly without any build step. The tricky part is handling cross-platform symlink support, particularly on Windows where symlinks require administrator privileges, so the implementation includes a fallback to copying files when symlink creation fails, ensuring dev mode works across all platforms even if symlinks aren't available.

Technical Details:

• Location: src/briefcase/platforms/web/static.py - StaticWebDevCommand
• New method: setup_dev_assets(app, venv)
• Uses _discover_editable_packages() from PR 2
• Creates symlinks in www/static/ for each package
• Fallback to shutil.copytree() if symlinks fail (Windows)
• Expected structure: www/static/toga_web/, www/static/travertino/, etc.

---

PR 4: Dev Mode HTML and PyScript Configuration

This PR generates the HTML and PyScript configuration needed for dev mode to function. The web template's index.html contains empty insert markers (<!--@@ head-python:start/end @@--> and <!--@@ body-python:start/end @@-->). In production builds, these markers are filled with content extracted from toolkit wheels, but dev mode doesn't build wheels. This PR implements the content that fills the head-python and body-python insert slots for dev mode. It creates content for the head-python slot (PyScript CDN links), the body-python slot (<py-config> and <py-script> tags), and generates a pyscript.toml file that tells PyScript how to find the symlinked Python modules. The implementation tests whether PyScript requires explicit files patterns or can discover modules automatically, and generates the minimal working configuration for the symlinked dev environment.

Technical Details:

• Location: src/briefcase/platforms/web/static.py - StaticWebDevCommand
• New methods: _fill_python_slots(app), generate_dev_pyscript_config(app, venv)
• Must fill empty insert markers in template's index.html
• Generate pyscript.toml with either files list or minimal config
• Unknown: exact PyScript config format needed - requires testing
• May need browser testing to validate configuration works

---

PR 5: HTTP Server Integration & run_dev_app

This PR brings everything together and actually runs the dev server. It overrides the run_dev_app() method in StaticWebDevCommand to orchestrate the complete dev workflow: it calls setup_dev_assets() from PR 3 to create symlinks, generates the PyScript configuration from PR 4, and then launches the HTTP server to serve the www/ directory with all the symlinked source code. The implementation reuses the existing LocalHTTPServer from StaticWebRunCommand (already handles CORS, proper MIME types, etc.) and supports the same CLI options like --host, --port, and --no-browser for consistency with the run command. This is where everything comes together—when you run briefcase dev web, it sets up the symlinked environment, starts a local server on localhost:8080, opens your browser, and you have full hot-reload capability: edit any Python source file in your IDE, hit refresh in the browser, and instantly see your changes without any build step.

Technical Details:

• Location: src/briefcase/platforms/web/static.py - StaticWebDevCommand
• Override method: run_dev_app(app, env, venv, passthrough, **options)
• Orchestrates: symlink creation, config generation, HTTP server startup
• Reuses LocalHTTPServer from StaticWebRunCommand
• Supports CLI options: --host, --port, --no-browser
• Handles graceful shutdown (Ctrl+C)

---

Known Challenges

1. PyScript Configuration Format - Unknown whether PyScript requires explicit files lists or auto-discovers. PR 4 needs browser testing.

2. Windows Symlink Support - Requires admin privileges or for developer mode to be enabled on users device.3.

3. Browser Caching - Potential issue with cached .py files. HTTP server includes cache-control headers.

4. Large Dependency Trees - Many dependencies may slow initial setup on Windows .

---

Other Work

• While PR Modify Dev Web Command to Support Editable Installs For Pure Python Requirements  #2498 already limits editable installs to local dependencies, future work can be done to extend this to URL based dependencies. More details is provided in the open PR discussion.

---

Handover from: @mEp3ii2, @JMah007

[JMah007]

@freakboy3742 Here is our handover report. Let us know if anything else needs to be added.

[freakboy3742]

Looks great - thanks for your work on all this @JMah007 & @mEp3ii2 !