App Backend Bridge
When to use
Whenever the app calls an API or uses auth.
Inputs
- Backend framework, deployed backend URL, auth library and transport.
Procedure
- Never rewrite the backend. Changes are limited to CORS and cookie settings, proposed to the user as a diff first.
- App origins to allow:
capacitor://localhost(iOS),http://localhostandhttps://localhost(Android),https://tauri.localhost(Windows),tauri://localhost(macOS, Linux). - CORS per backend, with credentials when cookies are used:
- FastAPI:
CORSMiddleware(allow_origins=[...], allow_credentials=True, allow_methods=["*"], allow_headers=["*"]). - Express / NestJS:
cors({ origin: [...], credentials: true })/app.enableCors({...}). - Django:
django-cors-headers,CORS_ALLOWED_ORIGINS,CORS_ALLOW_CREDENTIALS = True, plusCSRF_TRUSTED_ORIGINS. - Next.js route handlers:
Access-Control-Allow-Originecho of the allowed origin +OPTIONShandler.
- FastAPI:
- Auth: prefer bearer tokens stored with
@capacitor/preferences(or secure storage plugin) / Tauri store; cookies needSameSite=None; Secure. Android Capacitor can useCapacitorHttp/CapacitorCookiesto avoid cross-origin cookie limits. - API base URL from env at build time (
VITE_API_URL,NEXT_PUBLIC_API_URL), HTTPS only. - Sidecar (desktop only, when the app needs a local backend): bundle the binary via Tauri
bundle.externalBinand spawn it with the shell plugin, scope limited to that binary.
Verification
curl -i -X OPTIONS <api>/health -H "Origin: https://tauri.localhost" -H "Access-Control-Request-Method: GET" returns the origin; login then an authenticated call succeed in the app.
Failure modes and fixes
- CORS error: origin missing or
*with credentials. - Logged out after reload: cookie
SameSite=Laxblocked oncapacitor://localhost/https://tauri.localhost; use tokens orSameSite=None; Secure. - Mixed content:
http://API blocked; use HTTPS.
Deliverable
Backend patch proposal (applied only with consent) and the app API config; report step backend.
