==========
Static Web
==========

+--------+-------+---------+--------+---+-----+--------+-----+-------+
| Host Platform Support (:ref:`platform-support-key`)                |
+--------+-------+---------+--------+---+-----+--------+-----+-------+
| macOS          | Windows              | Linux                      |
+--------+-------+-----+--------+-------+-----+--------+-----+-------+
| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
+========+=======+=====+========+=======+=====+========+=====+=======+
| |f|    | |y|   | |v| | |f|    | |v|   | |v| | |f|    | |v| | |v|   |
+--------+-------+-----+--------+-------+-----+--------+-----+-------+

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

.. admonition:: Web support is experimental!

    `PyScript <https://pyscript.net>`__ (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
    <https://pyodide.org/en/stable/usage/wasm-constraints.html>`__ 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.briefcase.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"
    """
