Assets and the dev loop

The build contract

Two rules, and neither is configurable in peko.toml:

1. The web build must output to assets/, not dist/.
2. Asset URLs must be relative, because the asset server serves under a prefix and absolute paths will 404.

For Vite that means:

export default defineConfig({
  base: './',
  build: { outDir: 'assets', emptyOutDir: true },
  resolve: { dedupe: ['react', 'react-dom', 'vue'] },
})

peko project new writes this for you. The dedupe entry matters because the client SDK is linked from a local path and must resolve your app's own copy of the framework.

On every build the CLI copies each dependency's client directory into .peko/client/ and registers it in package.json, then runs npm install if needed and npm run build.

How assets are embedded

Per platform: copied into the app bundle on macOS and iOS, into the APK on Android, into the AppImage on Linux, and compiled into the executable as resources on Windows. Your code reaches them the same way everywhere.

The asset server

A loopback HTTP server serves the bundle. Three behaviors worth knowing:

• It binds a dynamic port each launch, which is the cause of the storage trap on the previous page.
• It serves only under its own prefix; anything else is a 404.
• A request whose last path segment has no dot is treated as a client-side route and served index.html. That makes history-mode routing work on reload and on a deep link.

Range requests are supported, so audio and video seeking works.

The dev loop

peko run

This starts your framework's dev server with npm run dev, scrapes the URL it prints, and points the native window at it. Web edits then reload through the framework's own HMR with no involvement from Peko.

A change to a .peko file recompiles the native binary incrementally, kills the app, and relaunches it with the route you were on restored.

So a UI project must have a dev script. Without one the command stops and points you at peko build.

The watcher covers the source directory, the entry file's directory, and peko.toml. It deliberately ignores web assets, since those belong to the dev server.

In dev mode the app skips the asset server, skips single-instance handling, and skips deep-link registration, because the dev server owns the origin.

peko run --devtools adds a diagnostics window driving the same loop.