Packaging and distribution¶
A NativeHTMLKit application is an ordinary Python program that depends on the nativehtmlkit
wheel; the wheel bundles the native host for its platform.
Project layout¶
Start from nativehtmlkit-new myapp --name "My App" (app.py, index.html, style.css,
pyproject.toml, optional app.toml); project scaffolding explains
each file and how to grow and test the project.
Locate assets relative to your code, never the current directory:
HERE = Path(__file__).resolve().parent
window = app.open_file(HERE / "index.html")
For an installed package, keep HTML/CSS/images as package data and resolve them with
importlib.resources.files("mypackage") / "ui" / "index.html" (a real file path when installed
normally), or load the markup as a string with load_html(..., asset_root=...).
Distribute as a Python package¶
[project]
name = "myapp"
version = "1.0.0"
requires-python = ">=3.10"
dependencies = ["nativehtmlkit==0.1.2"]
[project.gui-scripts]
myapp = "myapp.app:main"
Users install with uv tool install myapp and start myapp; during development, uv run -m myapp
(with a myapp/__main__.py that calls main()) or uv run myapp work in the project.
Application.start() re-runs the same Python command as the backend. On Linux this was checked
for installed script launchers and -m; on Windows, -m uses the same mechanism as
uv run app.py, while generated .exe script launchers were not part of the 0.1.2 checks, so try
yours before relying on it.
Platform support follows the nativehtmlkit wheels: Linux x64 (glibc 2.39+) and Windows x64,
Python 3.10+. The source distribution of nativehtmlkit has no host.
Identity and data¶
- Give the application a stable
app_id(Application.start(app_id="com.example.MyApp")). It controls single-instance hand-off and names the per-app directories fromdesktop.paths. - Store user data under
app.rpc.call("desktop.paths")["data"](orconfig/state), create the directory yourself and write files atomically (write a temporary file, thenos.replace). - Set
name,versionandiconinApplication.start(...).
Explicit manifests¶
For launchers, desktop entries or installers that should start a fixed interpreter, use a manifest
and nativehtmlkit-python-host run --app /path/to/app.toml (format).
{app_dir} in manifest strings is replaced by the manifest's directory. The backend then connects
with Application.start() or Application.from_environment().
Before you ship¶
- Run your UI headless in CI (
NATIVEHTMLKIT_TEST_MODE=1) and assert on DOM state. - Test once on each real desktop you support: native dialogs, clipboard, focus and window placement depend on the platform.
- Do not set
NATIVEHTMLKIT_HOST_BINARYin production; the bundled host is hash-verified on every launch.
Source: nativehtmlkit-python/docs/guides/packaging-and-distribution.md ยท edit the page there.