Converting a web app

Most of the work is adding a native half. The web app itself barely changes.

The steps

1. Add the manifest. In the project root:

[project]
name = "My App"
bundle = "com.example.myapp"
version = "0.1.0"
entry = "src/main.peko"
target_platforms = ["macos", "windows", "linux"]

[ui]
framework = "static"
width = 1200
height = 800

[dependencies]
pekoui = "0.1.6"

Running peko project new inside an existing web app detects the framework and offers to do this overlay for you.

2. Point the build at assets/.

base: './',
build: { outDir: 'assets', emptyOutDir: true },

3. Make sure dev and build scripts exist. The dev loop needs dev.

4. Import the client from your web entry:

import '@peko/client'

Do not npm install @peko/client; it is not published. The CLI links it from your Peko install and self-heals that on every build.

5. Write the native entry at src/main.peko:

import pekoui as ui;

fn on_start() {
    ui::app::from_bundle().run()
}

6. Replace browser storage with peko.storage.*. See the storage page for why this one is not optional.

Then peko run for the dev loop and peko build for bundles.

What changes

Web assumption	In a packaged app
localStorage, cookies, IndexedDB	not durable; the origin changes each launch
absolute asset URLs like /logo.png	404; use relative URLs and base: './'
fetch to your own origin	there is no server in a static build; use bridge handlers
client-side routing	works, including reload and deep links
window.open and tabs	use peko.windows.open
alert, confirm, prompt	webview-dependent; render HTML instead
native file pickers	only pick_folder exists
mobile safe areas	the SDK sets viewport-fit=cover; use the env() insets

What stays the same

Your components, your router, your styling, your state management, your build tooling, and your dev server all work unchanged. The bridge is an addition, not a replacement: an app can start as a plain web app in a window and adopt native capabilities one handler at a time.

A note on build hygiene

After changing the CLI or the toolkit, a plain peko build can produce stale output. Reinstall, then peko clean and build again.