Next.js + Capacitor 8 iOS: React state (messages, user data) lost on every app resume — WKWebView issue?

[Schuhanzieher]

BODY:

Environment

• Capacitor 8.1.0
• Next.js 15.3 (Remote URL mode — app loads from Vercel, not bundled)
• Supabase (Auth + Realtime + PostgreSQL)
• iOS 17+, WKWebView
• React 19

Problem

We have a production social app running via Capacitor in Remote URL mode (the WebView loads https://our-app.vercel.app). The core issue: every time the user minimizes and reopens the app, React state is lost — chat messages disappear, karma points reset to 0, VIP access is revoked temporarily.

This has been happening for weeks despite extensive debugging. The app works perfectly on first load and during active use, but any background/foreground cycle causes data loss.

What we've tried (and what didn't work)

1. App.addListener("appStateChange") + visibilitychange — We trigger auth token refresh and data re-fetch on resume. The events fire correctly, but the re-fetch responses arrive AFTER React state has already been cleared.

2. Module-level caches — We cache critical data (conversations, unread counts) at module level (outside React components) so they survive re-renders. This works for some hooks but not all.

3. subscribeWithRecovery() — We built a wrapper around Supabase Realtime .subscribe() that auto-reconnects on CHANNEL_ERROR. Channels do reconnect, but the associated React state is empty.

4. Reducing auth recovery dispatches — We went from 3-wave recovery (300ms, 1s, 2.5s) to a single dispatch at 150ms. Reduced the cascade but didn't fix the core issue.

5. getSession() instead of getUser() — getUser() makes a server call that fails during the brief token-refresh window on resume. Switching to local getSession() helped for auth checks, but data still disappears.

Specific symptom

User opens Messages → sees 50 messages + TicTacToe game
User presses Home button (iOS)
User opens app again (< 5 seconds later)
→ Chat is empty, shows loading spinner, then loads fresh from DB
→ But during the 1-2s reload window, user sees blank screen

The same happens for:

• Karma points (reset to 0 on resume, then reload)
• VIP access (blocked on resume because karma briefly = 0)
• Typing indicators (channel torn down on resume)

Key question

Is there a known pattern for preserving React state across iOS background/foreground cycles in Capacitor Remote URL mode?

Specifically:

1. Does WKWebView terminate the JS context on background, or just suspend it?
2. Is there a way to prevent React from unmounting/remounting the component tree on resume?
3. Should we persist ALL React state to localStorage and restore it on mount, or is there a cleaner approach?

Relevant code

Our recovery flow in the Supabase client singleton:

// client.ts — fires on every resume
const triggerRecovery = async () => {
  const now = Date.now();
  if (now - lastRecoveryAt < 3000) return; // 3s debounce
  lastRecoveryAt = now;

  // 1. Refresh token if needed
  const { data } = await _client.auth.getSession();
  if (data.session?.expires_at) {
    const expiresInMs = data.session.expires_at * 1000 - Date.now();
    if (expiresInMs < 120_000) {
      await _client.auth.refreshSession();
    }
  }

  // 2. Reconnect Realtime WebSocket
  _client.realtime.setAuth(
    (await _client.auth.getSession()).data.session?.access_token ?? null
  );
  _client.realtime.connect();

  // 3. Tell all hooks to re-fetch
  dispatchAuthRecovery();
};

Our hooks listen via useAuthRecovery() which fires the callback. But by the time the callback runs and data is fetched, the UI has already flashed empty.

System info

Capacitor CLI: 8.1.0
Capacitor iOS: 8.1.0
iOS deployment target: 14.0
Xcode: 16.x
Node: 22.x

Any help or pointers to similar resolved issues would be greatly appreciated!

[MukundaKatta]

This is almost certainly WKWebView killing your web content process in the background, not a Capacitor or Supabase issue. It's a well-documented but annoying iOS behaviour, and the symptoms match exactly.

What's actually happening

When your app goes to background, iOS puts pressure on the WebKit content process (WebContent.app). On iOS 17+, that pressure is more aggressive: if the OS needs memory for another app, it kills the WebContent process outright. The native container stays alive, so when the user returns, WKWebView silently reloads the URL — and because you're in remote URL mode, that's a full cold boot of your Next.js app.

Your appStateChange / visibilitychange handlers fire, but by the time they do, React has already remounted into a fresh tree. There is no state to refresh; there's nothing there yet.

The giveaway diagnostic: on every "resume" where state is lost, look at your server access logs. You should see a fresh request for your HTML document (and a bunch of chunks) at the moment the user foregrounds the app. If you see that, it's process termination — not Supabase, not React, not your auth refresh cadence.

How to confirm it in 30 seconds

Add this before any React rendering, in _document.tsx or an early script:

console.log('[cold-boot]', Date.now(), performance.timing?.navigationStart)
window.addEventListener('pagehide', (e) => {
  console.log('[pagehide]', { persisted: e.persisted })
})
window.addEventListener('pageshow', (e) => {
  console.log('[pageshow]', { persisted: e.persisted })
})

From Safari's Web Inspector attached to the device, reproduce the bug. If [cold-boot] fires with a fresh timestamp after resume, the process died. If you only see [pageshow] { persisted: true }, it's bfcache (a different problem, also worth knowing about).

The only fixes that actually work

1. Don't live in remote URL mode for a long-running stateful app.

This is the real answer for your use case. Capacitor's remote URL mode was designed for hybrid shells around mostly-idempotent content. For a social app with live messages and per-user state, either:

• Embed the Next.js build in the Capacitor app (next build && next export, point webDir at out/), so every "cold boot" is instant and state hydrates from local storage immediately. You still call Supabase for data; nothing else changes. This removes the server round-trip from the critical path and dramatically reduces the window where state loss is visible.
• Or switch to a bundled-shell approach and only remote-load specific sub-trees via fetch inside the app.

2. Treat every resume as "the web app might have restarted"

If staying in remote URL mode is non-negotiable:

• Persist the critical slice of state (messages, karma, VIP flags) to Capacitor Preferences on every change (debounced), not just localStorage — Preferences survives the WebView going away.
• On app mount, before rendering the shell, hydrate from Preferences synchronously.
• Use @capacitor/app appStateChange only to trigger a server reconcile, not to restore state. Local-first, server-reconcile-second.

// hooks/useHydratedState.ts
import { Preferences } from '@capacitor/preferences'

export function useHydratedState<T>(key: string, initial: T) {
  const [value, setValue] = useState<T>(initial)
  // Synchronous-ish rehydrate on mount
  useEffect(() => {
    Preferences.get({ key }).then(({ value: v }) => {
      if (v) setValue(JSON.parse(v))
    })
  }, [key])
  // Persist on change
  useEffect(() => {
    Preferences.set({ key, value: JSON.stringify(value) })
  }, [key, value])
  return [value, setValue] as const
}

Don't put messages: [] in React state and nothing else — that array is gone when the process dies. Put it behind useHydratedState and the cold-boot reload becomes invisible to the user.

3. React to process termination explicitly

iOS fires webContentProcessDidTerminate on the native side. In the Capacitor 8 iOS runner, you can listen for it from native:

// ios/App/App/AppDelegate.swift or a custom plugin
extension CAPBridgeViewController {
    override open func webViewWebContentProcessDidTerminate(_ webView: WKWebView) {
        // Optional: show a "reconnecting..." overlay, log telemetry, force a reload path
        webView.reload()
    }
}

The default Capacitor behaviour reloads; overriding it lets you show UI or flush logs. More importantly, knowing this event exists helps you see the bug in crash logs — it's the "why did my users see blank screens" signal.

4. Stop fighting the symptoms

Your "3-wave recovery" and tuned auth token refresh timing are chasing a different model of the bug. Auth token refresh at 150ms doesn't help because React state was already zero at 0ms. Once (1) or (2) is in place, you can remove the whole recovery-wave apparatus — reconcile-on-resume becomes a simple re-fetch, not a race against state restoration.

Why this isn't a Supabase issue

Supabase Realtime re-subscribes fine; your logs confirm CHANNEL_ERROR → subscribe cycles. The Realtime channel is emitting messages into an empty React state because React is fresh — the events go nowhere visible because there's no subscriber component mounted yet, or it's mounted with [] as its initial state. Fix the state-hydration layer and Realtime events start landing again correctly.

TL;DR

• Enable the console probe above to confirm process termination (90% probability this is what you're seeing).
• Move off remote URL mode, OR treat every mount as cold-boot and hydrate from Capacitor Preferences.
• Everything else (auth wave timing, realtime recovery) is downstream of those two.

Happy to look at a minimal repro if you put one together.