Ownership of PyScript, Bootstrap and Shoelace should be moved to Toga from Briefcase/Web-Template

[caydnn]

TL;DR

Migrating the ownership of PyScript, Bootstrap and Shoelace, from Briefcase to Toga itself. The main goal of this major change is to successfully break the framework dependencies such as PyScript and Shoelace that are presently coupled with Briefcase, allowing Toga to independently declare and handle its own runtime dependencies. In addition, this specific alteration will leverage the new insert system that has been developed, which enables the dynamic injection of critical components like HTML, CSS, and JavaScript at build time.

Background

Currently, Briefcase's web template has made use of hardcoded frontend tools that are important for functionality such as,

1. PyScript (for running Python in the browser)
2. Shoelace or Bootstrap (for UI components and styling)

This tightly couples Briefcase to specific versions of frontend tools. But:

• Frameworks like Toga should own their own runtime dependencies.
• Updating something like the PyScript version requires changes to Briefcase itself, which creates friction.
• There's no clear way for Toga to override or specify these dependencies.

This becomes especially problematic when frameworks evolve faster than Briefcase releases, or when template-level changes break downstream apps.

Existing PRs Connected to This Issue

Briefcase#1285

• Includes a feature that is referred to as the insert system.
• The insert system allows for Python packages to directly integrate HTML
  content into the index.html file. In addition, it facilitates adding
  CSS styles directly into the application's stylesheet.
• Adds index.html and briefcase.css placeholders for these inserts.
• Removes the old style_framework templating logic.

What can we take from this:

• src/briefcase/platforms/web/static.py.
  • Changes made to static.py to insert content provided from packaged wheels.
  • _write_inserts, _merge_instert_content, _write_bootstrap

Briefcase-web-static-template#9

• Includes insert markers.

• <!--@@ header:start @@--> and <!--@@ header:end @@--> in HTML

• /***@@ CSS:start @@***/ and /***@@ CSS:end @@***/ in CSS

• Removes embedded Shoelace/Bootstrap links.

• Adds support for a splash screen and other injected assets.

What can we take from this:

• Cookiecutter.json
  • Remove style_framework from cookiecutter
• {{cookiecutter.format }}/www/index.html
  • Remove cookiecutter style_framework templating for,
    • Bootstrap
    • Shoelace
  • Add Insert markers

Toga#1945

• Refactors Toga’s web backend infrastructure to enable the contribution of inserts.
• inserts/index.html:header: Shoelace styles and scripts.
• inserts/toga.css: layout and UI styles.
• Lays groundwork for similar insert-based control over PyScript.

What can we take from this:

• web/src/toga_web/inserts/index.html:header
  • These are the html scripts to be injected.
• web/setup.cfg
  • Adds inserts/ directory to the package_data

Proposed Fix

@kavi2du and I propose to attempt to fix this as a part of the deliverables the Curtin team (@mEp3ii2, @vt37, @Stringer90, @kavi2du, @JMah007, @caydnn) are aiming to achieve by the end of Semester 2 (~End of October, 2025). Our current, basic idea at the moment is to:

• Review and resurrect specific parts of the PRs mentioned above (Add the ability to test web apps #1285, Update web backend to support test mode toga#1945, Add support for inserts and test mode briefcase-web-static-template#9).
• Consult with the Toga Web Testing deliverable team (@vt37 and @Stringer90) to determine their approach to their deliverable and highlight any overlap. The PRs above also cover Russell’s initial idea for implementing a Web Testing framework, we will need to see if the other team will be also resurrecting this.
• Potentially update Pyscript and Bootstrap in Toga after architectural change.

The main goal here is for Toga to define dependencies for pyscript, shoelace and bootstrap and have these ‘injected’ into the html when Briefcase is building the web application.

We are also looking to hear feedback or suggestions from the wider Beeware community. If there’s anything anyone would like to mention or comment on, please let us know.

References

briefcase-web-static-template#9: beeware/briefcase-web-static-template#9
toga#1945: beeware/toga#1945
briefcase#1285: #1285

[freakboy3742]

This is a good summary of a collection of WIP tickets that have been idle for a while. Turning the bones of those existing PRs into finalized PRs would definitely be a worthwhile improvement.

For the purposes of your contribution, I don't think we need to consider the testing angle. Including testing and playwright into the existing PRs is the main reason those PRs didn't get finalized in their existing state; "how to test web" is definitely orthogonal to decoupling style framework choice from Briefcase.

Two open questions that I can see:

Firstly: How far can we decouple PyScript as a dependency of Briefcase? At present, Briefcase injects content into a pyscript.toml file provided by the web template - but that content will, by its nature, be in the format of a particular version of Pyscript. If a new version of Pyscript changes the format of pyscript.toml, then the content inserted by Briefcase may not be in the correct format. Ideally, Toga would be specifying that it needs Pyscript vX.Y.Z, and then ensuring the the pyscript.toml file is in the correct format. But - there is content for that file that only Briefcase is in a position to provide: the list of wheel files that Briefcase will package with the app.

Briefcase also currently defines the extra_pyscript_toml_content extension point, allowing a Briefcase user to inject additional content into their app template. What is the future of that extension point if Pyscript is no longer a hard dependency?

So - how far can we go down this path? Can we remove all references to PyScript from Briefcase? Or do we need to set Pyscript as a "baseline" requirement? And if so - is it a GUI framework's responsibility to inject all the HTML HEAD content to load pyscript, or should a GUI framework be specifying a PyScript version that it wants, and leaving it to the Briefcase template

To be clear - having Briefcase say "you have to use PyScript" and embedding certain Pyscript pieces into the Briefcase side of things isn't a deal-breaker. I just want to make sure we're clear about exactly what the roles are responsibilities are.

Secondly: What happens when there are 2 projects that want to provide inserts? In normal usage, you'd only expect Toga-web to be providing content to insert - but what happens if I have a second "web GUI toolkit" in my dependency list? Is there any conflict in having 2+ packages providing inserts? If PyScript is completely decoupled - what happens if toolkit 1 says "Pyscript vX" and toolkit 2 says "Pyscript vY"? What (if any) error handling is possible or desirable here?

[freakboy3742]

If we went with the first option, I think there's a couple of possible interpretations depending on the exact merging strategy that is used to combine the template-provided configuration, the Toga-provided configuration, and the user-provided configuration (ie., What's the merge order? Which one takes priority if a key is defined in two places?). Making one (or both) optional could be possible interpretations there.

Using the second option, and restricting the configuration to be entirely provided (and required to be provided) by the web toolkit has two benefits that I can see:

1. We don't have to define a merge priority (ie., does the Toga config override the template, or vice versa?). If we just move responsibility to Toga, then we have a single base configuration, dependencies provided by Briefcase, and the user extensions. This is essentially identical to what we have now, except that it's Toga providing the base configuration, rather the web template.
2. It means we have a clear point of validation - only a single library can provide a Pyscript configuration, so if we find a Pyscript configuration in more than one dependency, we know we've got a problem; and if we don't find a configuration at all, we also know we have a problem (because there's clearly no web GUI code to run).

On that basis, I think I agree with you that the second option - keeping the base pyscript.toml definition and version entirely in the domain of Toga (or the web library) - makes more sense. If nothing else, it also makes the implementation simpler :-)

I'm not aware of any external libraries that Briefcase is currently compatible with - but Python on Web is very much new territory. I consider this more of a case of setting up the conditions to allow other alternatives to emerge, rather than having a specific goal in mind.

The one existing use case I can forsee would be a "bare Pyscript" deployment - that is, someone who isn't using a Pyscript-compatible GUI toolkit, but is writing an app directly against the Pyscript API. In that case, the Pyscript configuration would be part of their own app code, rather than something brought in by a dependency.

[kavi2du]

Hi Russell, @caydnn and I wanted to share an update on where things currently stand regarding the division of responsibilities between Toga and Briefcase:

Define PyScript.toml Ownership and Integration

Responsibilities

• Toga provides the base PyScript version file
• Toga will own and supply version dependencies for Pyscript, Shoelace and Bootstrap
• Briefcase:
  • Merges in wheel paths under [tool.PyScript.packages]
  • Appends user-defined extra_PyScript_toml_content

Merge Rule

• Only one toolkit can define this base TOML. If multiple or no TOML files are found, Briefcase will raise an error
• Update setup.cfg/pyproject.toml in Toga to include the static PyScript.toml inside the Toga wheel. This will ensure this file is available for Briefcase at runtime when building the app

  [options.package_data]
  toga_web =
      inserts/**
      static/**
      PyScript.toml

HTML and CSS Inserts

• Add the HTML and CSS inserts (Toga/PR#1945, web/src/toga_web/inserts/index.html:header)
• Insert markers in the template
  • HTML
    <!--@@ header:start @@-->
<!--@@ header:end @@-->
  • CSS
    /***@@ CSS:start @@***/
/***@@ CSS:end @@***/

Changes in Toga

• Toga will now own the base PyScript configuration and version declaration (location - /toga/web/PyScript.toml)
• The file content would look like something similar to this

  [tool.PyScript]
  version = "2024.05.1"

Changes in Briefcase

A few changes need to be made in platforms/web/static.py file:

• During the build step, Briefcase will:

  • Locate and load a base PyScript.toml from Toga’s (or another GUI toolkit) wheel from the root directory of the wheel known path
  • Ensure that only 1 exists across all wheels
  • Raise error if 0 or greater than 1 PyScript.toml is found
  • Find the PyScript version defined in the toml, use it as the current PyScript for writing the rest of the toml and remove this declaration from the toml
  • Continue appending additional wheel paths and merge user-supplied extra_PyScript_toml_content
  • Write the final PyScript.toml to /build/appname/web/static/www/

• Add handling for html insert markers (eg. <!-- @ insert:start CSS @ --?>)

  • This will allow GUI Toolkits (Toga or otherwise) to define and dynamically insert their custom HTML headers and CSS
  • Inserts will be extracted from wheel paths such as toga/web/src/toga_web/inserts/index.html:header

Changes in the Briefcase Web Template

• Delete PyScript.toml file
• Remove all hard coded Pyscript, shoelace, bootstrap from index.html
• Use the insert markers in index.html and
  briefcase.css

[freakboy3742]

• Briefcase:
  • Merges in wheel paths under [tool.PyScript.packages]
  • Appends user-defined extra_PyScript_toml_content

Two notes here:

1. I don't know if this is an autocarrot problem, but be careful with capitalisation here - it's extra_pyscript_toml_content
2. [tool.PyScript.packages] - what is this? The tool. prefix suggests it's a PEP 518 pyproject.toml definition, but Briefcase can't (or shouldn't) be doing anything with a PyScript tool definition; pyscript.toml isn't subject to PEP 518, and doesn't need a table header to define requirements (it's a top-level packages = [...] definition).

Merge Rule

• Only one toolkit can define this base TOML. If multiple or no TOML files are found, Briefcase will raise an error
• Update setup.cfg/pyproject.toml in Toga to include the static PyScript.toml inside the Toga wheel. This will ensure this file is available for Briefcase at runtime when building the app

  [options.package_data]
  toga_web =
      inserts/**
      static/**
      PyScript.toml

Capitalisation on pyscript.toml, but otherwise this looks on track.

The only addition I might make is whether these three files should be grouped into a single folder - so the "deployment assets" would be deploy/inserts/**, deploy/static/**, and deploy/pyscript.toml. That simplifies the package_data declaration slightly for every user, and ensures that all this "common content" is grouped together.

HTML and CSS Inserts

• Add the HTML and CSS inserts (Toga/PR#1945, web/src/toga_web/inserts/index.html:header)
• Insert markers in the template

Agreed.

Changes in Toga

• Toga will now own the base PyScript configuration and version declaration (location - /toga/web/PyScript.toml)

Agreed, with the capitalisation and file path notes from above.

• The file content would look like something similar to this

  [tool.PyScript]
  version = "2024.05.1"

Again - I'm unclear where this [tool.PyScript] definition is coming from.

No disagreement that version needs to exist, though; although to the best of my knowledge, it's not a valid pyscript.toml key, so I'm not sure if the existence of this key will be a problem.

I can see three possibilities here:

1. We include version as a known key (possibly under a table), and leave it in place, and Pyscript ignores it as an unknown config value
2. We include version as a known key (possibly under a table), and remove it as part of the Briefcase processing step
3. We put Briefcase-specific meta-configuration (at present, only this version, and maybe a redundant backend="pyscript" definition to allow for future options in this space) into its own .toml file.

Changes in Briefcase

A few changes need to be made in platforms/web/static.py file:

Agreed - this all looks as I'd expect.

Changes in the Briefcase Web Template

Again - this all looks as I'd expect.

One additional detail worth considering - @mEp3ii2 and @JMah007 will have overlapping needs here. Their proposal for a "dev web" mode will need to replicate some of these steps; so you'll need to coordinate with them on how to share those resources.

[caydnn]

No disagreement that version needs to exist, though; although to the best of my knowledge, it's not a valid pyscript.toml key, so I'm not sure if the existence of this key will be a problem.

I can see three possibilities here:

1. We include version as a known key (possibly under a table), and leave it in place, and Pyscript ignores it as an unknown config value
2. We include version as a known key (possibly under a table), and remove it as part of the Briefcase processing step
3. We put Briefcase-specific meta-configuration (at present, only this version, and maybe a redundant backend="pyscript" definition to allow for future options in this space) into its own .toml file.

After some conversation, we have decided that the 3rd option is the best way forward. Defining a pyscript version in the pyscript.toml is definitely unsupported and seems poor practice. We will ensure to include a briefcase.toml file for defining the pyscript version as well as the template pyscript.toml.

The only addition I might make is whether these three files should be grouped into a single folder - so the "deployment assets" would be deploy/inserts/**, deploy/static/**, and deploy/pyscript.toml. That simplifies the package_data declaration slightly for every user, and ensures that all this "common content" is grouped together.

Now that we have 2 .toml files, I think its best that the "deployment assets" also includes deply/configs/** which would contain both .toml files.

[freakboy3742]

After some conversation, we have decided that the 3rd option is the best way forward. Defining a pyscript version in the pyscript.toml is definitely unsupported and seems poor practice. We will ensure to include a briefcase.toml file for defining the pyscript version as well as the template pyscript.toml.

Ideally, what we're specifying here shouldn't be Briefcase specific. briefcase.toml works for template configuration files because it's Briefcase doing the consuming of that information; but in theory, this toga-web configuration file should be usable by another deployment tool - we're specifying everything needed to deploy the tool.

I'd lean towards pydeploy.toml or pyweb.toml - or, given the next point, maybe deploy/config.toml is enough.

The only addition I might make is whether these three files should be grouped into a single folder - so the "deployment assets" would be deploy/inserts/**, deploy/static/**, and deploy/pyscript.toml. That simplifies the package_data declaration slightly for every user, and ensures that all this "common content" is grouped together.

Now that we have 2 .toml files, I think its best that the "deployment assets" also includes deply/configs/** which would contain both .toml files.

I'd be wary of going too deep in a hierarchy for the sake of it. deploy/config.toml is a reliable and predictable location. It's "Top level deployment configuration" content. We don't gain anything by going super deep into deploy/config/config.toml. As a point of comparison: Python projects puts pyproject.toml (and other project configuration files) at the root of the project, and then content goes in src, docs, etc.

[caydnn]

Hi @freakboy3742, apologies for the delay. Here is our draft issue post:

Delegate ownership of PyScript, Shoelace and Bootstrap to Toga / GUI Toolkit

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

@kavi2du 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.toml file (similar to the file currently included in the Briefcase Web Template)
• A config.toml file containing a PyScript version for Briefcase configuration
• /inserts directory containing HTML script inserts
  • In Toga’s case this includes PyScript, Bootstrap and Shoelace headers
• /static directory containing static CSS code
  • For Toga this will be the current /static directory including toga.css

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

---

Comments section

Overview of changes

Responsibilities

Toga

Owns and supplies:

• Runtime version declarations for PyScript, Shoelace, and Bootstrap
• A valid pyscript.toml containing only PyScript config (e.g., plugins = ["!error"])
• A config.toml with version metadata for use in Briefcase (e.g., pyscript_version)
• HTML insert files for dynamic injection (e.g., index.html:header)
• Static CSS files for Toga styling (e.g., toga.css)
• Ships all deployment-related files under: toga_web/deploy/

Briefcase

• Loads and processes deployment config.toml and pyscript.toml from toolkit wheels
• Merges:
  • Wheel paths into packages = [...] inside pyscript.toml
  • User-supplied extra_pyscript_toml_content
• Loads index.html from Briefcase Web Template
• Injects content from insert files using template markers into index.html

Briefcase Web Template

• Supplies index.html
• No longer supplies pyscript.toml

Merge Rule

• Briefcase requires exactly one deploy/config.toml file (errors if 0 or >1 found)
• config.toml defines:
  • pyscript_version: used by Briefcase to determine runtime injection behavior
  • Optional: backend = "pyscript" for future extensibility
• Briefcase also requires exactly one deploy/pyscript.toml file (errors if 0 or >1 found)
  • Must adhere to PyScript’s documentation
  • Currently only includes plugins = ["!error"]
• All insert/config/static assets must reside under deploy/

---

HTML and CSS Inserts

HTML:

<!--@@ header:start @@-->
<!--@@ header:end @@-->

CSS:

/***@@ CSS:start @@***/
/***@@ CSS:end @@***/

Briefcase loads insert content from deploy/inserts/** and injects it into templates.

---

Changes in Toga

New directory structure

toga/web/deploy/
├── config.toml
├── pyscript.toml
├── inserts/
└── static/

Example config.toml

pyscript_version = "2024.11.1"
backend = "pyscript"

Example pyscript.toml

plugins = ["!error"]

---

Changes in Briefcase

• Update platforms/web/static.py to:
  • Detect and load deploy/config.toml and pyscript.toml from GUI toolkit wheels
  • Validate ownership (only one config)
  • Use pyscript_version from config.toml
• Merge:
  • Wheel paths into packages
  • extra_pyscript_toml_content from user config
• Write final pyscript.toml to /build/<appname>/web/static/www/
• Inject insert content using defined markers into index.html

---

Changes in the Briefcase Web Template

• Remove:

  • Hardcoded links/scripts for PyScript, Shoelace, Bootstrap
  • pyscript.toml

• Add:

  • Insert markers in index.html and briefcase.css:

    <!--@@ header:start @@-->
    <!--@@ header:end @@-->

    /***@@ CSS:start @@***/
    /***@@ CSS:end @@***/

---

Roadmap

Phase 1: Foundation Setup

Goals:

• Prepare Toga to own its runtime dependencies
• Define structure for configuration and inserts

Tasks:

• Define and document the structure for deploy/ inside toga_web/
• Create initial example files: pyscript.toml, config.toml
• Add a test HTML/CSS insert (e.g., header with Shoelace)

---

Phase 2: Briefcase Processing Logic

Goals:

• Update Briefcase’s build system to support toolkit-owned config and inserts

Tasks:

• Modify platforms/web/static.py to:
  • Detect and load deploy/config.toml and pyscript.toml
  • Validate that only one toolkit provides deployment configuration
• Parse config.toml for pyscript_version and optional backend
• Merge wheel paths and extra_pyscript_toml_content into pyscript.toml
• Write final output to /build/<appname>/web/static/www/

---

Phase 3: Insert Injection System

Goals:

• Support injection of HTML and CSS inserts from toolkit-provided files

Tasks:

• Implement support in Briefcase for reading deploy/inserts/**
• Parse and match:
  • <!--@@ header:start @@--> to <!--@@ header:end @@-->
  • /***@@ CSS:start @@***/ to /***@@ CSS:end @@***/
• Replace insert markers in index.html and briefcase.css with corresponding insert content

---

Phase 4: Web Template Updates

Goals:

• Clean up the web template and switch to insert-based injection

Tasks:

• Remove:
  • Hardcoded <script> and <link> tags for PyScript, Shoelace, and Bootstrap
  • Static pyscript.toml
• Add insert markers to index.html and briefcase.css

---

Phase 5: Validation and Compatibility Testing

Goals:

• Confirm that the new system works end-to-end

Tasks:

• Build a Toga web app using Briefcase and validate build output
• Ensure pyscript.toml is correctly generated and contains valid runtime configuration
• Confirm insert behavior in HTML/CSS is correct
• Test user-supplied extra_pyscript_toml_content

---

Phase 6: Dev Web Coordination and Integration

Goals:

• Coordinate with other teams working on overlapping features
• Finalize implementation and prepare for upstream PRs

Tasks:

• Work with the dev web mode team to align shared responsibilities
• Document expectations for GUI toolkit integration
• Open PRs to Toga, Briefcase, and briefcase-web-static-template

[freakboy3742]

@kavi2du @caydnn Very thorough - nice work. Time to post it formally!