Skip to content

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

Closed

Description

@kavi2du

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.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

Activity

  1. added
    enhancementNew features, or improvements to existing features.
    on Jun 12, 2025
  2. freakboy3742 commented on Jun 12, 2025

    @freakboy3742
    Member

    @caydnn If you comment on this ticket, I can add you to the assigned list.

  3. caydnn commented on Jun 13, 2025

    @caydnn
    Contributor

    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 @@--> and <!--@@ header:end @@-->

    CSS:

    /***@@ CSS:start @@***/ and /***@@ 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 @@--> and <!--@@ header:end @@-->
      /***@@ CSS:start @@***/ and /***@@ 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
  4. freakboy3742 commented on Jun 13, 2025

    @freakboy3742
    Member

    @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.

  5. caydnn commented on Jun 13, 2025

    @caydnn
    Contributor

    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.

  6. freakboy3742 commented on Jun 13, 2025

    @freakboy3742
    Member

    Ah - well, feel free to reverse the edit as required.

  7. kavi2du commented on Jun 13, 2025

    @kavi2du
    ContributorAuthor

    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! : )

  8. caydnn commented on Jul 28, 2025

    @caydnn
    Contributor

    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

    1. Make a directory to contain your cloned repositories and navigate to it in your terminal.
      cd PyscriptDeliverables
      
    2. Go to Toga, Briefcase and the Briefcase Web Template github pages, make a fork of each then clone them.
      If you are reviewing PRs, make sure to fork the repository of the PR owner.
      git clone https://github.com/<your username>/briefcase.git
      git clone https://github.com/<your username>/toga.git
      git clone https://github.com/<your username>/briefcase-web-static-template.git
      
    3. Create and activate a virtual environment.
      python -m venv PyscriptDeliverable
      PyscriptDeliverable\Scripts\activate
      
    4. Make an editable install of Briefcase.
      cd briefcase
      python -m pip install -e .[dev]
      
    5. Finally, pick an example widget folder from your local Toga clone, open it's pyproject.toml and append template=path/to/your/web/template/checkout in the web configuration section, like so:
      # Web deployment
      [tool.briefcase.app.button.web]
      requires = [
          "../../web",
      ]
      template = "C:/path/to/briefcase-web-static-template"
      style_framework = "Shoelace v2.3"
      
    6. From within your virtual environment, navigate to and run the selected example.
      cd ..
      cd toga/examples/selectedExample
      briefcase run web
      
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew features, or improvements to existing features.

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions