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 bundlewarns 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 bundlehashes 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 bundlewarns 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.
Framework notes
Section titled “Framework notes”- SvelteKit:
adapter-staticwithfallback: 'index.html', andexport const ssr = falsein the root layout. - Vite SPA:
base: '/'. - Next.js:
output: 'export'withimages.unoptimized. Route handlers,proxy.ts/middleware,redirects(),headers()andnext/headersall 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.
Security
Section titled “Security”- No secrets in the bundle. Anyone can unpack an app. Anything that needs a private key stays on your server.
- No
evalornew Function. The CSP has nounsafe-eval. Check your dependencies as well as your own code..wasmis 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-srcis'none', because a bridge message cannot say which frame sent it. Payment, identity and captcha widgets open outside the bridge page, for example withopen.external. - No CSP meta tag. The host sends the policy as a header, from the signed manifest.
- No native code in the output.
valence bundlerejects.so,.dex,.jar,.dylib,.frameworkand 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.
Talking to native
Section titled “Talking to native”- Import from the generated
bridge.g.ts, so every call is type-checked against your schema. The one exception is the debug-onlytraceBridge. - Call
connect()once at startup, beforehas(). - 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_CANCELLEDmeans 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.
Network
Section titled “Network”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 withE_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 isE_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.
Mobile layout
Section titled “Mobile layout”- Respect the system bars with
--valence-inset-topand its siblings, including onposition: fixedheaders 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.*andprefs.*. TreatlocalStorageand IndexedDB as a cache. - External links use
open.external.
Store rules
Section titled “Store rules”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 bundlewarns 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.