beeware / beeware/briefcase

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

Open
#2,334 5 comments 0 reactions 2 assignees Claimed by @mEp3ii2 View on GitHub
enhancement
Dominant language
Python
Stars
3.3k
Forks
549
Avg merge
1d 4h
Merged PRs (30d)
40

Description

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 https://github.com/beeware/briefcase/issues/1104, and it should be noted that when [PEP 783](https://peps.python.org/pep-0783/) 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](https://docs.pyscript.net/latest/guides/filesystem/) for in-browser virtual filesystem implementation

---

## Roadmap of Changes: `briefcase dev` Support for Web

**1. Dev-Mode Command & Venv Management**

- [x] Implement `briefcase dev web` via a `WebDevCommand` subclass that respects platform and `--test` mode.
- [x] 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//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`.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.