Skip to content

Static Web

Host Platform Support
macOS Windows Linux
x86‑64 arm64 x86 x86‑64 arm64 x86 x86‑64 arm arm64
● ○ △ ● △ △ ● △ △

When generating a web project, Briefcase produces a static folder of HTML, CSS and JavaScript resources that can be deployed as a web site. The static website is packaged as a .zip file for distribution.

Although Briefcase provides a run command that can be used to serve the website, this web server is provided as a development convenience. It should not be used in production. If you wish to serve your app in production, you can unzip the .zip file in the root of any web server that can serve static web content.

Web support is experimental!

PyScript (which forms the base of Briefcase's web backend) is a new project; and Toga's web backend is very new. As a result this web backend should be considered experimental.

Regardless of what Python version you run Briefcase with, the app will use PyScript's current Python version (as of October 2022, this is 3.10).

There are also a number of constraints on what you can do in a web environment. Some of these are fundamental constraints on the web as a platform; some are known issues with PyScript and Pyodide as runtime environments. You shouldn't expect that arbitrary third-party Python packages will "just run" in a web environment.

Icon format

Web projects use a single 32px .png format icon as the site icon.

Web projects do not support splash screens or installer images.

Additional options

The following options can be provided at the command line when producing web projects:

run

--host <ip or hostname>

The hostname or IP address that the development web server should be bound to. Defaults to localhost.

-p <port> / --port <port>

The port that the development web server should be bound to. Defaults to 8080. If port 8080 is already in use, an arbitrary available port will be used.

--no-browser

Don't open a web browser after starting the development web server.

Application configuration

The following options can be added to the tool.static.app.<appname>.web section of your pyproject.toml file:

extra_pyscript_toml_content

Any additional configuration that you wish to add to the pyscript.toml file for your deployed site. For example, you can use this to change the runtime used by Briefcase when deploying your site.

extra_pyscript_toml_content is a string that defines valid TOML content; this content will be parsed, and used to add values to the pyscript.toml generated by Briefcase, overriding any pre-existing keys. For example, to define a custom runtime, and change the default PyScript app name, you could use:

extra_pyscript_toml_content = """
name = "My name override"

[[runtimes]]
src = "https://example.com/custom/pyodide.js"
"""

Deployment Configuration

Wheels can include information related to deployment that Briefcase will use to control how to serve web applications. This includes configuration of the Python runtime environment (such as the PyScript version), as well as snippets of HTML, CSS or JavaScript that are required for a wheel to behave as expected at runtime.

The deployment configuration is provided by including a deploy folder in the contents of the wheel as a child of the top level package folder. For example, if you have a package named mypackage, any content in the wheel in the mypackage/deploy folder will be used by Briefcase to aid deployment as a web site.

The following files and file types can be included in the deploy directory:

config.toml

Deployment settings are defined using a config.toml file located in the deploy folder. The deployment configuration file accepts the following information:

  • implementation: The web implementation to use (currently only "pyscript" is supported). If not specified, defaults to "pyscript".

  • pyscript.version: The PyScript version to use (e.g., "2024.11.1"). If not specified, Briefcase will use its default PyScript version.

Example config.toml:

implementation = "pyscript"

[pyscript]
version = "2024.11.1"

A Briefcase project must have only one package that defines deployment configuration through a config.toml file. Briefcase will raise an error if multiple packages in the dependencies attempt to define deployment settings.

pyscript.toml

A package can include a base pyscript.toml file located at <package>/deploy/pyscript.toml. The base configuration in this file serves as the foundation for Briefcase to generate the final pyscript.toml file. Briefcase will build the final pyproject.toml file using the following procedure:

  1. Briefcase reads the base pyscript.toml file from the wheel's deploy directory.
  2. Briefcase will add a packages definition to that base pyscript.toml that matches the requirements defined in your project's pyproject.toml.
  3. Any extra_pyscript_toml_content from pyproject.toml will be merged over the top of any existing configuration.

Inserts

A package can provide snippets of HTML, CSS, and JavaScript content that are to be inserted into specific locations (called "slots") in the generated web application. This is the recommended way to add custom web resources to your Briefcase web application.

When building an app for deployment, Briefcase will:

  1. Scans through all wheel files to detect insert content.
  2. Organize collected inserts according to their target files and slot names.
  3. Writes the accumulated content into designated slots in the target files.

Insert Slots

Any file generated by the Briefcase app template can to include slots that indicate where inserts should be placed. These slots are code comments that have a specific format that Briefcase can use to identify the location for inserted content:

  • HTML:

    <!--@@ slot-name:start @@-->
<!--@@ slot-name:end @@-->

  • CSS/JavaScript:

    /*@@ slot-name:start @@*/
/*@@ slot-name:end @@*/

Common insert slots in Briefcase web templates include:

  • head: Content to insert in the HTML <head> section of index.html
  • head-python: Content for the <head> used to configure the Python interpreter
  • body-start: Content at the start of the <body>
  • body-python: Content in the <body> used to configure the Python interpreter
  • body-end: Content at the end of the <body>
  • css: CSS content to be included in the site stylesheet.

Defining Insert Files

Python packages can include inserts by placing files inside the deploy/inserts/ directory which must use this naming convention:

    <package>/deploy/inserts/<path-to-target-file>~<slot-name>

Where:

  • The target file path is specified in relation to the project root directory appears as <target-file> (e.g., index.html or static/css/style.css).
  • The tilde (~) character separates the target path from the slot name.

For example, a package named mypackage could include the following files as inserts:

  • mypackage/deploy/inserts/index.html~head - Inserts into the head slot of index.html in the root of the deployment directory
  • mypackage/deploy/inserts/static/css/style.css~css - Inserts into the css slot of static/css/style.css