Skip to content
Valence is in beta. The bundle format and update protocol are meant to stay stable; the CLI, the generated code and the two runtime packages’ APIs may still change. What beta means

Web app checklist

Everything a web app has to do to run well inside a Valence host, on one page. Each section links to the guide that explains why. valence bundle and valence doctor catch some of these. The rest are yours to check.

  • The build is static files. There is no server on the phone, so no SSR, API routes, middleware or server actions in the bundle. Your server keeps running as an API.
  • Asset URLs are absolute from the origin root: /assets/app.js, not ./assets/app.js. The same entry page is served at every URL, so a relative URL breaks on every nested route. valence bundle warns about this in the entry page.
  • Routing happens on the client. Any path with no file extension gets the entry page, and your router takes it from there.
  • Inline scripts live only in the entry page. valence bundle hashes that page’s inline scripts into the CSP, and an inline script added at runtime is blocked. Other HTML files get no CSP header and no bridge nonce, so keep the whole app in the entry page.
  • No service worker. It answers from its own cache without asking the host, so an update can activate and still show the old page. valence bundle warns about this, including when a dependency registers one.
  • The bundle is a reasonable size. Files are unpacked on first launch, so thousands of small files cost real startup time. Measure it on a low-end phone.
  • SvelteKit: adapter-static with fallback: 'index.html', and export const ssr = false in the root layout.
  • Vite SPA: base: '/'.
  • Next.js: output: 'export' with images.unoptimized. Route handlers, proxy.ts/middleware, redirects(), headers() and next/headers all need a server, so they stay on your server or move to the client. Dynamic segments such as /users/[id] must list every id at build time, which a real app cannot do, so prefer /users?id=1. Treat a large existing Next.js app as a migration.
  • No secrets in the bundle. Anyone can unpack an app. Anything that needs a private key stays on your server.
  • No eval or new Function. The CSP has no unsafe-eval. Check your dependencies as well as your own code. .wasm is allowed.
  • No remote scripts. Tag managers, analytics snippets and SDKs that load code from a CDN are blocked. Bundle what you need, or send events through your API.
  • No third-party iframes. frame-src is 'none', because a bridge message cannot say which frame sent it. Payment, identity and captcha widgets open outside the bridge page, for example with open.external.
  • No CSP meta tag. The host sends the policy as a header, from the signed manifest.
  • No native code in the output. valence bundle rejects .so, .dex, .jar, .dylib, .framework and similar files.
  • Nothing sensitive in the console. The host forwards page console output to its log, in release builds too. Never log tokens, passwords or personal data.
  • Import from the generated bridge.g.ts, so every call is type-checked against your schema. The one exception is the debug-only traceBridge.
  • Call connect() once at startup, before has().
  • Call ready() once per page load on every path that paints, including error screens and empty states. A bundle that misses it twice is rolled back. See the web app guide.
  • Gate newer features with has(), because phones run hosts older than your bundle.
  • Handle every BridgeError. E_CANCELLED means the user backed out, which usually wants no message at all.
  • Keep each message small. Bridge messages are JSON, capped at 256 KB in each direction, so bytes such as photos and PDFs do not go through the bridge.

A page cannot call an arbitrary API from the app’s own origin, so use http.request. See Your backend.

  • Every API origin is listed in http.origins. The list is compiled into the store build, and an update cannot widen it. A missing origin fails with E_DENIED. Include every host your app calls, not only the main one.
  • Responses and request bodies fit the limit: requests 64 KiB; responses default to 64 KiB, raised only by compiled http.maxBodyBytes (1..262144), measured decompressed. The escaped reply still fits the separate 256 KiB envelope. A response that is 5 KB gzipped can be 130 KB here. Over the limit is E_TOO_LARGE. Measure your real payloads early.
  • Calls finish within 20 seconds, and bodies are UTF-8 text. Multipart uploads and binary downloads are out of scope for this method.
  • Your code handles redirects itself. They come back as 3xx and are never followed.
  • You know how your API authenticates. A bearer token works by default. A cookie session needs http.cookieJar, and a cookie with no expiry lasts only until the app restarts.
  • Writes are safe to retry, with a server-enforced idempotency key. A POST can succeed on the server while the page sees a failure.
  • Respect the system bars with --valence-inset-top and its siblings, including on position: fixed headers and footers. See Safe areas and accessibility.
  • The first launch works offline from the built-in bundle and seed, and never blocks on a download.
  • Durable data goes in native SQLite through data.* and prefs.*. Treat localStorage and IndexedDB as a cache.
  • External links use open.external.

See Store policy.

  • The app does more than wrap a website. Ship at least two native capabilities before the first store submission, such as offline use, notifications or widgets. See Store policy.
  • New feature areas ship through a store update, not over the air. valence bundle warns about new top-level routes.
  • No hidden features switched on after review, and the store listing matches what the app does.
  • Bundles contain only your own first-party UI, never other developers’ apps.
  • Debug tools are not in the release bundle. See Debugging.