Project
Stack, hosting and commands. The agent uses the commands to verify its own work; include the one that runs your tests.
Why the agent needs this file
Without context, an agent optimizes for the browser it knows. It adds a cookie wall, puts a Stripe button on the pricing page, forgets that the fixed footer sits on top of the iPhone home indicator, and happily removes the Delete account route during a refactor. Each of those is a store rejection. A CLAUDE.md file fixes this at the source: it tells Claude Code what the native wrapper is, which URL schemes exist, which store rules are non-negotiable and which routes must keep working.
Copy the template, replace the example values, commit it to the repository root. Claude Code picks it up automatically in that project, and so does anyone on your team who runs the agent.
The template
Replace the stack, the domain and the route list. Delete bridge lines you do not use; the file should describe your app, not every WebViewGold feature.
markdown
# CLAUDE.md
## Project
- Next.js (App Router), TypeScript, Tailwind. Supabase for auth and Postgres. Stripe for web checkout.
- Deployed on Vercel at https://app.example.com. Every production deploy is live in the native apps immediately.
- Commands: npm run dev, npm run lint, npm run test, npm run build. Run lint and tests before reporting done.
## Native app context (read this first)
- This web app is also published as iOS and Android apps built with WebViewGold, a native WebView wrapper.
The apps load https://app.example.com in a WKWebView / Android WebView. There is no separate mobile codebase.
- The apps send a custom user agent that contains the token WebViewGoldApp.
Use isNativeApp() from src/lib/native.ts to branch. Never duplicate the user agent check.
- Native features are triggered by navigating to a URL scheme: window.location.href = "scheme://...".
Results come back as injected global JavaScript variables or as calls to global functions.
Full reference: https://www.webviewgold.com/llms-full.txt. Read the relevant section before adding a feature.
- Only call a scheme when isNativeApp() is true. In browsers use the web equivalent or hide the control.
- On iOS, several scheme calls in one script run must be combined: multiapicall://getonesignalplayerid,getappversion
## WebViewGold bridge used in this project
- Push permission: registerpush:// (shows the system prompt). Status: checkNativePushPermissions:// then read
window.nativePushEnabled after a short delay. System settings: settingsapp://
- Push user ID: getonesignalplayerid:// then read window.onesignalplayerid; store it on the user profile.
- Local notification: sendlocalpushmsg://push.send?s=SECONDS=msg!MESSAGE&!#TITLE&!#URL
Cancel all: sendlocalpushmsg://push.send.cancel
- Biometrics: bioauth:// then the wrapper calls window.onBioAuthSuccess(), window.onBioAuthFailure(code, message)
or window.onBioAuthUnavailable(). Treat success as a UI gate only; the server session stays the source of truth.
- Scanner: qrcode:// opens the native scanner and loads the scanned URL in the app.
barcodescanner:// then read window.barcodescanresult.
- Share sheet: shareapp://message?=TEXT&url=URL (URL-encode both values).
- Haptics: lighthaptic://, heavyhaptic://, successhaptic://, warninghaptic://, errorhaptic:// (mediumhaptic:// is iOS only).
- Downloads: savethisimage://?url=IMAGE_URL saves to the photo library; links ending in .pdf, .docx, .xlsx or .mp3
download natively.
- Purchases: revenuecat://purchase?external_id=USER_ID&product=PRODUCT_ID. Entitlements arrive through the
RevenueCat webhook at /api/webhooks/revenuecat and are stored in the subscriptions table.
- App version: getappversion:// then read window.versionNumber. Rating prompt: rateapp://
## Store rules (never break these)
- Apple 4.2: the app must do more than the website. Push, offline handling and the share sheet must keep working.
- Apple 4.8: a third-party login exists, so Sign in with Apple stays available and equally prominent.
- Apple 5.1.1 and Google Play: /privacy must describe real data practices; Delete account stays in settings and works.
- Apple 3.1.1 and Google Play billing: inside the native app, digital goods go through revenuecat://, never Stripe.
Never render external payment links or web prices when isNativeApp() is true.
- Apple 2.3: no beta labels, no coming-soon screens, no placeholder content in production.
- Apple 4.0: safe-area padding on fixed bars, 44 px tap targets, no horizontal overflow at 320 px width.
- Never add Download our app banners, builder badges or cookie walls.
## Conventions
- Mobile first. Verify every UI change at 320 px, 390 px and at iPad width.
- Every data fetch has loading, empty and error states with a retry action.
- Secrets stay server-side. The client bundle must never contain a service-role key or a webhook secret.
- Routes the native apps and store listings depend on: /, /login, /privacy, /terms, /delete-account, /settings.
Changing or removing one of them requires a note in docs/native-app.md.What each block does
Native app context
The single most important block. It explains that there is a WebView, how to detect it, that native features are URL schemes, and where the documentation lives. The llms-full.txt link lets the agent look up details itself instead of guessing.
Bridge used in this project
Only the schemes you actually use, with their return variables. This prevents invented API names, which is the most common mistake an agent makes with any bridge.
Store rules
Each line maps to a guideline number so the agent can explain its own decisions in a diff summary. Keep the list short; a long list of rules gets skimmed.
Conventions
Breakpoints, state handling, secrets and the protected routes. The protected-routes line is what saves you from a refactor that silently removes /delete-account.
Great way of converting your web app to a native app! Fast turn-around, and a great way to get your apps into the app stores without the need to develop a full native app!
Adapting the template
Set the user agent token in WebViewGold
The template assumes the apps identify themselves. In Config.swift set
useragent_iphoneanduseragent_ipad, in Config.java setUSER_AGENT, each to a normal mobile user agent string followed by a space andWebViewGoldApp. Leaving them empty uses the default system user agent, which your code cannot distinguish from Safari or Chrome.Create the helper the file refers to
Ask Claude Code: "Create src/lib/native.ts with isNativeApp() as described in CLAUDE.md and a callNative(scheme) function that sets window.location.href only when isNativeApp() is true." Everything else can build on those two functions.
Trim the bridge list
Delete lines for features you have not enabled in the WebViewGold projects. A scheme that is listed but not switched on in Config.swift (for example push without a push service) does nothing at runtime and confuses debugging.
Keep it current
When you enable a new native feature or change a protected route, update the file in the same commit. Claude Code can do that for you if you ask it to "update CLAUDE.md to reflect this change".
Scheme reference the agent will rely on
| Feature | Call | Result |
|---|---|---|
| Push permission | registerpush:// | System prompt; later checkNativePushPermissions:// sets nativePushEnabled |
| Biometric check | bioauth:// | Calls onBioAuthSuccess(), onBioAuthFailure(code, message) or onBioAuthUnavailable() |
| QR scanner | qrcode:// | Scanned URL is loaded in the app |
| Share sheet | shareapp://message?=TEXT&url=URL | Native share dialog |
| Purchase | revenuecat://purchase?external_id=…&product=… | Store purchase sheet; entitlement via RevenueCat |
| Push user ID | getonesignalplayerid:// | Sets onesignalplayerid |
Frequently asked questions
Does the same idea work for Cursor or Codex?
Yes. Cursor reads project rules files and Codex reads AGENTS.md. The content is the same; only the file name and location differ. See the Cursor rules and AGENTS.md templates in this section.
Should I paste the whole WebViewGold documentation into CLAUDE.md?
No. Link to llms-full.txt and list only the schemes you use. A huge context file dilutes the rules that matter and the agent can fetch details on demand.
Where do I keep settings that differ between iOS and Android?
In the template itself, as a short note next to the scheme (for example that mediumhaptic:// is iOS only). For larger differences, add a docs/native-app.md file and reference it from CLAUDE.md.
Can Claude Code write the CLAUDE.md for me?
It can draft one from the codebase, but it does not know about the native wrapper unless you tell it. Start from this template, then ask the agent to fill in the stack and route details.
Three ways to get your app into the stores
Same result, different amount of work on your side. All three come with the approval guarantee and 24/7 human support.
Do it yourself
$109 per platform, one-time
The WebViewGold license: a finished Xcode or Android Studio project. Paste your URL, set name and icon, switch on features, build and submit. Free updates forever.
See plans on the main pageCloud Builder
$349 per license, one-time add-on
No Mac, no Xcode, no Android Studio: configure in the browser, we build both apps in the cloud and hand them to App Store Connect and the Play Console.
How the Cloud Builder works Try the free demoFull Service
$698 per platform $798
Send us your URL and icon. Our team configures, builds and delivers your app within 72 hours, white-label, with source projects. Both platforms for $1,158.
Full Service details Powered by
Winter Sale prices valid until December 31, 2026.