Platform-Aware briefcase dev Command with Editable Installs for Web Development
- 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
Assessment
This issue has not been assessed yet.