ovllib_dev 0.1.3

Make desktop overlays using existing web-techs

ovllib_dev

ovllib_dev is a small CLI for creating desktop overlay projects with modern web tooling. It can scaffold a frontend project, generate an overlay configuration file, and package the built static site into a .ovl archive.

Features

• Interactive project setup
• Support for React, Vue, Solid, SvelteKit, and vanilla Vite projects
• TypeScript and JavaScript project templates
• Package manager support for npm, pnpm, yarn, and bun
• Static build configuration for overlay packaging
• .ovl archive generation from frontend build output

Requirements

• Python 3.10 or newer
• uv for local development
• One supported JavaScript package manager:
  • npm
  • pnpm
  • yarn
  • bun

The selected package manager must be installed before running project setup or build commands.

Installation

pip install ovllib_dev
ovllib_dev --version

Usage

Create a new overlay project

ovllib_dev init

The setup flow asks for:

• Project name
• Package manager
• Frontend framework
• Frontend language

After confirmation, ovllib_dev creates the frontend project and writes an ovl_config.toml file into the generated project directory.

Build an overlay package

From inside a generated overlay project, run:

uv run python /path/to/ovllib_dev/main.py build

The build command:

1. Reads ovl_config.toml
2. Runs the configured frontend build command
3. Copies the static frontend output and overlay config into a temporary package
4. Creates a .ovl archive in the configured build output directory

By default, packaged overlays are written to:

build/ovl/<project-name>.ovl

Configuration

Generated projects include an ovl_config.toml file like this:

# Auto-generated by ovl setup

[project]
name = "my-overlay"
entry_dir = "web"
entry_file = "index.html"

[window]
width = 600
height = 400
x = 40
y = 40
movable = true
move_element = ""

[build]
framework = "react"
package_manager = "npm"
frontend_output = "build"
build_dist = "build/ovl"

Project settings

• name: Project and output package name
• entry_dir: Directory inside the package that contains the frontend files
• entry_file: HTML file used as the overlay entry point

Window settings

• width and height: Initial overlay size
• x and y: Initial overlay position
• movable: Whether the overlay can be moved
• move_element: Optional selector or element identifier used for dragging

Build settings

• framework: Frontend framework selected during setup
• package_manager: Package manager used for build commands
• frontend_output: Static frontend build directory
• build_dist: Directory where .ovl packages are written

Supported frontend stacks

Framework	TypeScript	JavaScript
React	Yes	Yes
Vue	Yes	Yes
Solid	Yes	Yes
SvelteKit	Yes	Yes
Vanilla	Yes	Yes

Vite-based projects are configured to emit static files into build. SvelteKit projects are configured with @sveltejs/adapter-static and prerendering enabled.

Development

Run the CLI locally:

uv run python main.py init
uv run python main.py build

Check Python syntax:

uv run python -m py_compile main.py build.py init.py

Project structure

.
├── build.py          # Packages a built frontend into a .ovl archive
├── init.py           # Interactive project scaffolding
├── main.py           # CLI entry point
├── pyproject.toml    # Python project metadata and dependencies
├── uv.lock           # Locked Python dependencies
└── README.md

Notes

• robots.txt is excluded from packaged frontend output.
• Existing overlay build output is ignored while copying frontend files, which prevents previously generated .ovl packages from being nested in new builds.
• The build command expects ovl_config.toml to be present in the current working directory.