Mobile App Architecture

Akan mobile apps are built by opening a CSR web client inside a Capacitor native shell, then packaging that shell as Android and iOS apps. The screen is developed with the same Akan UI system, while Capacitor provides the native project, app identity, and device bridge.

Akan mobile architecture

If the app declares multiple basePaths, one Akan app can release multiple mobile packages. For example, a customer app, an admin stock app, and a field worker app can each open a different basePath while sharing the same services, permissions, database rules, and generated fetch calls.

apps/myapp/akan.config.ts

CSR web surface: The app opens a Single Page Application client, not a separate native UI rewrite.

Capacitor package: Capacitor wraps the CSR client with Android and iOS project files, app metadata, and device APIs.

Shared business logic: Web and mobile use the same Akan service, signal, document, auth, and generated client helpers.

CSR Web Workflow

Akan mobile work starts as normal UI work. Build the page, component, st state, fetch calls, and dictionary text the same way you would for the web. Then test it as a CSR Single Page Application before packaging it into Android or iOS.

Open a CSR page in the browser

The csr=true search parameter is useful when you want to check SPA navigation, client state, page transition, and mobile-like behavior from the browser. This is faster than opening the simulator for every small UI change.

Enable sync navigation while developing

Sync navigation is a local development helper. When enabled, Akan's HMR channel broadcasts CSR navigation between open clients, so a browser, simulator, and physical device can follow the same route while you tune mobile layout and transitions.

page/store/product/[productId].tsx

transition: Optional override for the platform default. If you do not set it, Akan chooses an iOS/Android-native feel automatically: iOS detail pages default to stack, Android detail pages default to scaleOut, and tab/root pages default to none.

safeArea: Handles OS system areas such as notches, home indicators, and Android edge-to-edge system bars. Android avoids double padding unless reliable edge-to-edge inset values are available.

topInset / bottomInset: Handles app UI space through CSR frame layers. Layout.Navbar, Layout.BottomTab, and Layout.BottomInset register this automatically; keyboardSticky BottomInset is isolated into the keyboard layer while normal bottom UI stays in the bottom chrome layer.

keyboardSticky: On mobile CSR, keyboardSticky BottomInset becomes a keyboard accessory. The framework resizes the primary page scroll container, so mobile pages should let .akan-page-content own the main scroll instead of creating a separate primary overflow container.

cache: Keeps CSR page state when users return to list or tab screens.

Android edge-to-edge safe area

android: "auto": Default Android behavior. Akan uses CSS safe-area values only when they are present, which avoids adding duplicate padding in normal Android WebView layouts.

android: "edge-to-edge": Use when the Android app draws behind the status bar or navigation bar. Akan applies the larger value from native device insets and CSS safe-area insets so content can avoid system bars.

android: "none": Disables Android safe-area padding for pages that manage system-bar spacing manually or intentionally use an immersive/full-bleed surface.

Akan CSR pages can apply mobile-style page transitions from pageConfig. Use the demos below to compare the four transition presets in a browser CSR environment before packaging the same pages into a native shell.

bottomup

Good for modal-like flows or pages that should rise from the bottom.

fade

Keeps the movement calm when the screen context changes without hierarchy.

scale

Adds a light zoom motion for focused entry into the next page.

stack

Works well for detail pages that push over a list or parent screen.

FAQ: Are hybrid apps worse than native apps?

Akan improves the user experience with page transitions, safe-area handling, inset support, CSR page cache, and mobile pageConfig. Device capabilities are not blocked by the hybrid model: Capacitor plugins can bridge camera, Bluetooth, device, haptics, keyboard, safe area, and other native APIs when needed.

Deep Links

Mobile targets can open Akan CSR routes from native URL schemes and verified web links. Akan writes the native iOS and Android project settings, packages the mobile target metadata, and routes the incoming URL through the CSR router.

apps/myapp/akan.config.ts

schemes: Custom native URL schemes such as example://orders/detail. Akan adds iOS CFBundleURLTypes and Android VIEW intent filters.

domains: Verified HTTPS app links such as https://example.com/orders/detail. Akan serves the association files from /.well-known/apple-app-site-association and /.well-known/assetlinks.json.

indexPath: Fallback CSR route used when a deep link needs to rebuild a mobile navigation stack or when the hardware back button has no previous route.

When domains are configured, iOS requires deepLinks.ios.teamId. Android release builds require deepLinks.android.sha256CertFingerprints so the generated assetlinks.json can verify the package signature.

Deep link URLs are normalized into CSR paths. If the target route exists in the route manifest, Akan can restore the closest existing parent stack before pushing the final route.

Android Packaging Workflow

Use the Android flow when you want to run the CSR client in an emulator/device, verify the native Android project, or prepare Play Store artifacts. Akan prepares the Capacitor project, syncs Android, applies metadata, and builds APK or AAB outputs.

Run on emulator or device: Use startAndroid while developing screens and checking live reload.

Build native package: Use buildAndroid to prepare the Android project and verify the release bundle.

Release for Play Store: Use releaseAndroid with a non-local env and a store-ready assemble type such as aab.

Android commands

Android local prerequisites

apps/myapp/package.json

Declare the Capacitor packages that your app uses in the app package.json with "*" versions. This lets Capacitor sync discover and link native plugins from the app project, while the workspace controls the actual installed versions.

Android release needs stable package identity and signing. Keep appId stable after release, increase buildNum for native releases, and prepare release keystore settings for Play Store artifacts.

For device APIs and Capacitor details, use the Capacitor documentation as the native bridge reference. Capacitor Docs

iOS Packaging Workflow

Use the iOS flow when you want to run the CSR client in the iOS simulator/device, verify the Xcode project, or prepare App Store artifacts. Akan prepares the Capacitor project, syncs iOS, applies bundle metadata, and opens or builds the native project.

Run on simulator or device: Use startIos while developing screens and checking live reload.

Build native project: Use buildIos to prepare the iOS project, sync Capacitor, and verify the native build.

Release for App Store: Use releaseIos with a non-local env, then finish signing, archive, and submission in the Apple toolchain.

iOS commands

For iOS, keep the same app-level Capacitor dependencies in apps/myapp/package.json before running start-ios or build-ios. If a plugin is missing there, the JavaScript module can load while the native iOS plugin is not linked, causing "plugin is not implemented" errors in the simulator.

iOS release needs stable bundle identity and Apple signing setup. Keep appId stable after release, increase buildNum for native releases, and verify provisioning, certificates, and App Store Connect settings before submission.

Native Build Troubleshooting

Most mobile build issues come from native toolchain setup, plugin sync state, or confusing local mode with release mode. Check these items before debugging page code.

Android SDK: Set ANDROID_HOME or android/local.properties so Gradle can find the SDK. Start an emulator or connect a device before running start-android.

Java 21: Capacitor Android builds require a Java 21 compiler. If you see invalid source release: 21, update JAVA_HOME and PATH to JDK 21.

Plugin sync: After adding or removing Capacitor packages, rerun start-ios/start-android or a build command so native projects regenerate plugin files.

iOS plugins: If Safari console says a plugin is not implemented, the JavaScript module loaded but the native plugin was not linked. Check app package.json and rerun iOS sync/build.

Safe area: safeArea handles device system bars; topInset and bottomInset handle app UI such as nav bars, tabs, and fixed bottom actions.

Common local fixes

Local mode uses a live server.url and does not package built CSR assets into the native app. Release mode builds CSR output first and copies the target HTML into the Capacitor webDir.