Repository navigation
Description
Initial discussion at #2283
What is the problem or limitation you are having?
Briefcase currently owns the configuration of frontend web dependencies PyScript, Shoelace, and Bootstrap, via hardcoded values in the Briefcase Web Template. This tightly couples Toga (and other Web GUI Toolkits) to Briefcase and the Web Template, creating several limitations:
- GUI toolkits like Toga cannot define or upgrade their own runtime stack without changes in Briefcase/Web Template.
- PyScript configuration is entangled with Web Template logic, preventing clear version control or modular updates.
- Toolkit-level concerns (runtime versions, UI styling) are mixed with packaging-level concerns (wheels, app paths), which hinders maintainability and growth of the BeeWare ecosystem.
Describe the solution you'd like
@caydnn and I propose that we introduce a clear separation of responsibilities between Toga (GUI Toolkit) and Briefcase (Packager) by delegating ownership of runtime dependency configuration and insertion content to Toga/GUI-Toolkit.
Toga and 3rd Party GUI Toolkits would contain a deployment/ directory containing:
- Base/Template
pyscript.tomlfile (similar to the file currently included in the Briefcase Web Template) - A
config.tomlfile containing a PyScript version for Briefcase configuration /insertsdirectory containing HTML script inserts- In Toga’s case this includes PyScript, Bootstrap and Shoelace headers
/staticdirectory containing static CSS code- For Toga this will be the current
/staticdirectory includingtoga.css
- For Toga this will be the current
During the build process, Briefcase would gather and integrate these resources with index.html and other files from the Briefcase Web Template.
Expected Outcomes
- GUI Toolkits/Toga will have more control over the frontend dependencies
- Briefcase remains a packager with less focus on defining the internals of a GUI Toolkit
- Toga maintenance improved through owning dependencies—for example, taking advantage of new features or fixes from dependency updates will now require a single PR to Toga rather than an additional PR to the Briefcase Web Template
Further details for our solution can be found in the comments below.
Describe alternatives you've considered
-
Considered entirely decoupling PyScript from Briefcase
Not feasible as this will require Toga/GUI Toolkits to package their own PyScript wheels. This would stray from their intended scope. -
Embedding PyScript version in
pyscript.toml
Rejected as this is not valid in accordance with PyScript documentation. -
Keeping dependency configuration in Briefcase/Briefcase Web Template
Limits GUI toolkit flexibility and creates difficulty in maintaining Toga. -
Using deep nested folders (e.g.,
deploy/configs/)
Rejected as this nested structure is unnecessary.
Additional context
- We will need to coordinate with @mEp3ii2 and @JMah007 and their "dev web" mode as our changes to the build process will impact their work.
- This work builds upon the following PRs by @freakboy3742
- briefcase#1285: Insert system
- toga#1945: Insert refactor for Toga
- briefcase-web-static-template#9: Insert marker support
Activity
freakboy3742 commentedon Jun 12, 2025
@caydnn If you comment on this ticket, I can add you to the assigned list.
caydnn commentedon Jun 13, 2025
Overview of changes
Responsibilities
Toga
Owns and supplies:
pyscript.tomlcontaining only PyScript config (e.g.,plugins = ["!error"])config.tomlwith version metadata for use in Briefcase (e.g.,pyscript_version)index.html:header)toga.css)toga_web/deploy/Briefcase
config.tomlandpyscript.tomlfrom toolkit wheelspackages = [...]insidepyscript.tomlextra_pyscript_toml_contentindex.htmlfrom Briefcase Web Templateindex.htmlBriefcase Web Template
index.htmlpyscript.tomlMerge Rule
deploy/config.tomlfile (errors if 0 or >1 found)config.tomldefines:pyscript_version: used by Briefcase to determine runtime injection behaviorbackend = "pyscript"for future extensibilitydeploy/pyscript.tomlfile (errors if 0 or >1 found)plugins = ["!error"]deploy/HTML and CSS Inserts
HTML:
CSS:
Briefcase loads insert content from
deploy/inserts/**and injects it into templates.Changes in Toga
New directory structure
Example
config.tomlExample
pyscript.tomlChanges in Briefcase
platforms/web/static.pyto:deploy/config.tomlandpyscript.tomlfrom GUI toolkit wheelspyscript_versionfromconfig.tomlpackagesextra_pyscript_toml_contentfrom user configpyscript.tomlto/build/<appname>/web/static/www/index.htmlChanges in the Briefcase Web Template
Remove:
pyscript.tomlAdd:
index.htmlandbriefcase.css:Roadmap
Phase 1: Foundation Setup
Goals:
Tasks:
deploy/insidetoga_web/pyscript.toml,config.tomlPhase 2: Briefcase Processing Logic
Goals:
Tasks:
platforms/web/static.pyto:deploy/config.tomlandpyscript.tomlconfig.tomlforpyscript_versionand optionalbackendextra_pyscript_toml_contentintopyscript.toml/build/<appname>/web/static/www/Phase 3: Insert Injection System
Goals:
Tasks:
deploy/inserts/**<!--@@ header:start @@-->to<!--@@ header:end @@-->/***@@ CSS:start @@***/to/***@@ CSS:end @@***/index.htmlandbriefcase.csswith corresponding insert contentPhase 4: Web Template Updates
Goals:
Tasks:
<script>and<link>tags for PyScript, Shoelace, and Bootstrappyscript.tomlindex.htmlandbriefcase.cssPhase 5: Validation and Compatibility Testing
Goals:
Tasks:
pyscript.tomlis correctly generated and contains valid runtime configurationextra_pyscript_toml_contentPhase 6: Dev Web Coordination and Integration
Goals:
Tasks:
freakboy3742 commentedon Jun 13, 2025
@caydnn Thanks - I've edited your comment to remove the duplicated content. There's no reason to duplicate half of the original ticket content as a comment. If there's something new you need to add, you can add it assuming the rest of the ticket has been read by other users.
caydnn commentedon Jun 13, 2025
Apologies @freakboy3742, I should've explained.
The reason for the duplicate is that section of the post was meant for the comment section and was mistakenly included in the main post. Kavi was going to edit the post once he returned from work.
freakboy3742 commentedon Jun 13, 2025
Ah - well, feel free to reverse the edit as required.
kavi2du commentedon Jun 13, 2025
Apologies guys, I accidentally used an older version of the draft issue ticket when I published this issue earlier today. I've updated the main issue ticket now with the latest changes and the overview is now in Caydn's comment. Sorry for the confusion! : )
caydnn commentedon Jul 28, 2025
Hi all, below is our current set of instructions for running a test of all three repositories together. I've tested it myself and works for me but please let me know if they don't work or if you see any issues :)
How to use local development versions of Briefcase and Toga together
If you are reviewing PRs, make sure to fork the repository of the PR owner.
pyproject.tomland appendtemplate=path/to/your/web/template/checkoutin thewebconfiguration section, like so: