Migrating a Next.js (App Router + Server Components/Actions) app from Capacitor server.url to an embedded, offline-first build (Android + iOS). Who has done it?

[Dassproffen]

I have an app in production on Android and iOS built with Next.js 16 (App Router, Server Components, Server Actions) + Supabase, wrapped with Capacitor 8 loading the remote site through server.url. It also runs as a PWA (Serwist service worker, data cached in IndexedDB).

The requirement: users must open and use the app offline and on weak signal (the "connected but nothing loads" 4G case), like Spotify or Google Maps offline. Usage is mostly reading, with a few writes queued offline.

What I've learned so far: the Capacitor team says server.url is meant for development, not production. That matches our experience: on a cold start with weak signal the WebView sits on a black screen for 30s+ and falls into errorPath, because the app shell doesn't live on the device. Service-worker tweaks (NetworkFirst, CacheFirst, StaleWhileRevalidate, navigation preload) helped in some cases and broke others, and they behave differently on Android WebView and iOS WKWebView (App-Bound Domains, storage eviction).

The direction seems clear: embed the front-end in the binary and use Live Updates for OTA. My questions are about the migration:

1. How did you handle Server Components and Server Actions? Did you convert them to API routes on the hosted Next app called by absolute URL, move reads to the Supabase client with RLS, or something else?
2. output: 'export' or another setup? Any problems with dynamic routes like /events/[id]/...?
3. Which Live Updates provider do you use (Capgo, Capawesome, Appflow) and why? Anything to watch for with App Store and Play Store rules?
4. Does anything change between Android and iOS in this setup: storage limits, eviction, background sync?
5. Can the migration be done gradually (mobile embedded, desktop web stays as it is)?

Real-world experience, repositories or articles are very welcome. Thanks!

[Rami-init]

1. Server Components / Server Actions

An embedded build has no server, so Server Actions aren't available (output: 'export' fails with "Server Actions are not supported with static export"). You also can't call the hosted app's actions from the app: action IDs change on every build, and Next checks the Origin header.

• Reads: supabase-js with RLS, directly from the device.
• Writes: Route Handlers or Edge Functions, called by absolute URL. The app's origin is capacitor://localhost on iOS and https://localhost on Android, so allow those in CORS or enable CapacitorHttp.

2. output: 'export' and /events/[id]

A dynamic segment without generateStaticParams fails the build, and events created after the build wouldn't have a page anyway. Use one static page instead:

// app/events/page.tsx  ->  /events?id=123
import { Suspense } from 'react'
import EventView from './event-view'

export default function Page() {
  return <Suspense><EventView /></Suspense>
}

// app/events/event-view.tsx
'use client'
import { useSearchParams } from 'next/navigation'

export default function EventView() {
  const id = useSearchParams().get('id')
  // load the event by id with supabase-js
  return <main>Event {id}</main>
}

Map deep links like /events/123 to this page in App.addListener('appUrlOpen', ...).

3. Live Updates

• Appflow: no new customers, and service ends 31 Dec 2027. Capgo and Capawesome Cloud are the alternatives.
• Google Play exempts "JavaScript in a webview" from its self-update rule. Apple allows downloaded interpreted code as long as it doesn't change the app's primary purpose.
• Changes to native plugins still have to go through the stores.

4. Android vs iOS

• WebView storage can be evicted (see Capacitor's storage guide). Use SQLite for offline data and Preferences for small values, including the Supabase session:

import { createClient } from '@supabase/supabase-js'
import { Preferences } from '@capacitor/preferences'

const nativeStorage = {
  getItem: async (key: string) => (await Preferences.get({ key })).value,
  setItem: (key: string, value: string) => Preferences.set({ key, value }),
  removeItem: (key: string) => Preferences.remove({ key }),
}

export const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  auth: { storage: nativeStorage, persistSession: true, autoRefreshToken: true, detectSessionInUrl: false },
})

• Service workers don't register under capacitor:// on iOS (bug: Service workers fail to register on iOS via WKWebView, potentially feature request? #7069), so Serwist's data caching has to move into app code.
• Queue offline writes in SQLite and flush the queue on the resume and networkStatusChange events. @capacitor/background-runner runs only when the OS decides to run it (about 30 s per run on iOS, a minimum 15 min interval on Android).

5. Gradual migration

Yes. Keep apps/web (SSR + Server Actions) as it is and add apps/mobile (static export). Both share the UI and a data layer with two implementations.

Checked against Next.js 16.3.6.

[charles-benedito]

Im not sure about the reply above but capacitors own config doc marks server.url as "intended for use with live-reload servers" and "not intended for use in production", so the black screen on weak signal is just what that mode does

the catch is next, not capacitor. an embedded build means output: 'export', and the static export docs list what stops working: server actions, route handlers that read the request, cookies, headers, isr, draft mode, and dynamic routes without generateStaticParams. server components can stay as long as they resolve at build time i think, but every server action has to become a plain api call to your backend (supabase straight from the client, or an api route hosted seperately). thats usually the bulk of the migration

live updates for the bundle afterwards is a plugin thing (appflow or capgo), capacitor core doesnt ship it, but it slots in once the app is a static bundle. i wouldnt try to keep server.url and fix it with service worker tricks tho, u already saw how that goes on wkwebview

[riderx]

In case you need guide to NextJs in capacitor we maintain one here https://capgo.app/blog/building-a-native-mobile-app-with-nextjs-and-capacitor/