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`