image
Akan.js
Docs
DocsConventionsReferencesCheatsheet
English
image
Akan.js
Akan.js v2 docs are now available.View the v1 docs
DocsConventionsReferencesCheatsheet
Released under the MIT License
Official Akan.js Consulting onAkansoft
Copyright © 2026 Akan.js All rights reserved.
System managed bybassman
General
• Authorization
• Schema Design
• Edge Computing
• File Management
• Single Sign-On
• DataList & Enum
Interface
• CRUD
• Endpoint
• Form
Observability
• Logging
• Dependency Injection
• Error Handling
• Metrics
Performance
• Caching
• Image Optimization
• Lazy Loading
• Querying
• Mutating
• Queueing
• Realtime
Development
• Documentation
• Script
• Console
• Mobile
• Docker
• Kubernetes
• PWA
General
• Authorization
• Schema Design
• Edge Computing
• File Management
• Single Sign-On
• DataList & Enum
Interface
• CRUD
• Endpoint
• Form
Observability
• Logging
• Dependency Injection
• Error Handling
• Metrics
Performance
• Caching
• Image Optimization
• Lazy Loading
• Querying
• Mutating
• Queueing
• Realtime
Development
• Documentation
• Script
• Console
• Mobile
• Docker
• Kubernetes
• PWA
Previous
Console
Next
Docker

Mobile Setup Flow

Akan mobile apps reuse the CSR web app inside a Capacitor Android/iOS shell. The web app owns pages and business logic. The native shell owns package identity, device permissions, plugin linking, native files, signing, and store builds.
Start with the mobile identity, declare only the Capacitor plugins the app actually uses, then prepare Android and iOS builds. Push notifications and deep links are optional features; configure them only when the app needs them.
1. mobile config
App name, package id, version, target basePath, permissions, native files.
2. Capacitor plugins
List the native plugins used by this app in apps/myapp/package.json.
3. Android / iOS
Prepare platform toolchains, app IDs, signing, and sync/build commands.

Mobile Config

The mobile block in akan.config.ts describes the native package. These values become Android application metadata, iOS bundle metadata, target entry paths, native permission hints, and native file copy rules.
apps/myapp/akan.config.ts
appName: Native display name. Users see it on the launcher/home screen unless the platform or store overrides it.
appId: Stable native package identity. Android uses it as applicationId/package name; iOS uses it as bundle id. Any platform console registration must match it exactly.
version / buildNum: version is the user-facing version. buildNum is the store build number and must increase for every native store submission.
targets.default.basePath: The Akan client route opened by the native app. Use separate targets when one app repo ships separate customer/admin/partner apps.
permissions: Native capability hints such as "camera", "contacts", "location", and "push". They prepare Akan-side native metadata, but plugin-specific setup can still be required.
files: Copies app-owned files into generated native project paths. Use it for native config files that must live inside Android or iOS projects.
Do not change appId casually after release. Android and iOS treat a different appId as a different app.

Capacitor Plugins

Capacitor links native plugins from the app package. A workspace-level dependency is not enough if the app package does not declare the plugin. Add only the plugins your app actually calls.
Base mobile shell dependencies
Push notification add-on dependencies
Use * because the app package declares usage, not the resolved version. The workspace lockfile and root package control the actual installed version.
start-ios/start-android run Capacitor add/sync/run commands, but they do not add dependencies to apps/myapp/package.json. Declare the app dependencies first, then rerun the mobile command.
Usually package-only: Small bridge plugins such as haptics or device often work after package declaration and sync.
Package + native settings: Camera, geolocation, push, background work, file access, and auth plugins often require Info.plist, AndroidManifest, Xcode capabilities, Gradle settings, or console credentials.
After changing plugins: Run start-ios/start-android or a build command again. That regenerates native plugin files.

Android Setup

Android setup prepares a generated Android project that can build and run on an emulator or physical device. The important path is package name consistency: mobile.appId and the generated Android applicationId must match.
Prerequisites
  • Android Studio with Android SDK installed.
  • JDK 21 available from your shell.
  • A stable mobile.appId such as com.example.shop.
1. Configure local toolchain
2. Set Android package identity
3. Sync and build
start-android: Use during development. It prepares native files and runs the app on an emulator or connected device.
build-android: Use to verify the Android project builds without starting an interactive device run.
release-android: Use for store artifacts such as AAB. Release signing and Play Store settings matter here.
Success check
  • Generated applicationId matches mobile.appId.
  • The app runs on an emulator or physical device.
Push notifications are covered in Push Setup. Keep Android Setup focused on the native project and package identity first.

iOS Setup

iOS setup prepares the Xcode project, bundle identity, signing, simulator runs, and store-oriented builds. Push notifications are covered in Push Setup.
Prerequisites
  • Xcode installed.
  • A stable mobile.appId used as the iOS bundle id.
  • Apple signing setup when running on a physical device or releasing.
Xcode checks
  1. Open the generated iOS project after sync.
  2. Check that bundle identifier matches mobile.appId.
  3. Check signing team and provisioning when running on a physical device.
  4. Run the app in a simulator first, then move to a physical device for device-only features.
1. Sync and build
Push notifications are covered in Push Setup.

Push Setup

Push setup has three separate surfaces: web push, Android push, and iOS push. Akan gives one client API, usePushNotification(), but the platform setup is still different.
Akan automates
  • Serving /firebase-messaging-sw.js for web push.
  • Android POST_NOTIFICATIONS permission when target.permissions includes push.
  • iOS aps-environment, remote-notification background mode, and Capacitor AppDelegate bridge.
You provide
  • App package dependencies for Capacitor push and FCM.
  • Firebase web config, google-services.json, and GoogleService-Info.plist.
  • Firebase Console app registration and APNs credentials.
Web push
  1. Create or open a Firebase web app in Firebase Console.
  2. Copy the public Firebase web config into env.client.*.
  3. Create a Web Push certificate key pair and put the VAPID public key in vapidKey.
  4. Akan serves /firebase-messaging-sw.js automatically from the client Firebase config.
apps/myapp/env/env.client.local.ts
Android push
  1. Open Firebase Console and select the project.
  2. Add an Android app.
Android push file copy
google-services.json is a client/native Firebase config file. It is not the Firebase Admin service account JSON. Server credentials belong in env.server.*.
Android notification details
Android can require extra notification behavior outside token registration. Create channels when you need stable categories such as order updates or chat messages, set the default icon/color in the native project if the launcher icon is not appropriate, and decide foreground presentation behavior in app code.
iOS push
  1. Register an iOS app in Firebase using the same bundle id as mobile.appId.
  2. Download GoogleService-Info.plist.
iOS push file copy
Keep GoogleService-Info.plist in the app folder, then copy it into the generated iOS project with mobile.files. If Firebase Console sends to a token but nothing arrives while simctl push works, check the APNs development/production credential that matches the built aps-environment.
APNs environment mapping
start-ios
development
Local simulator/device runs use the APNs sandbox path.
build-ios
production
Release build generation uses the production APNs environment.
release-ios
production
Store/TestFlight release uses the production APNs environment.
Do not add firebase-ios-sdk directly in Xcode when using @capacitor-community/fcm. Direct Firebase Swift Package products can conflict with the plugin's Firebase dependency version.

Deep Link Setup

Deep links open a CSR route from outside the app. Use schemes for app-only URLs and domains for verified HTTPS links. Push notification clicks use the same routing path through data.url.
Think of deep link as the feature, and schemes/domains as the two common ways to implement it. Scheme links such as shop://orders/1 are easy to test and app-only. Domain links such as https://shop.example.com/orders/1 require iOS/Android verification, but they behave like normal web links and are better for sharing, emails, and push notification URLs.
apps/myapp/akan.config.ts
schemes: Custom app-only URLs such as shop://orders/1. Easy to test, but not domain-verified.
domains: Verified HTTPS links such as https://shop.example.com/orders/1. iOS uses apple-app-site-association; Android uses assetlinks.json.

Verify Setup

Do not stop at a successful build. Verify the actual feature surface: plugin availability, native file placement, permission prompt, push token creation, server send, and click routing.
Plugin available: If the console says plugin is not implemented, the JS package exists but the native plugin was not linked. Check app package.json and rerun sync/build.
Android push: Check package name, app/google-services.json, Google Services Gradle setup, notification permission, and Firebase project match.
iOS push: Check real device testing, aps-environment entitlement, APNs key upload, provisioning profile, and GoogleService-Info.plist target membership.
Click routing: Send a notification with url: /some/path and confirm tapping it opens the expected CSR route.
Mobile Setup Flow
Mobile Config
Capacitor Plugins
Android Setup
iOS Setup
Push Setup
Deep Link Setup
Verify Setup
Why two Capacitor plugins?
@capacitor/push-notifications handles the OS push bridge: permission, native registration, notification click events, and Android channels. @capacitor-community/fcm handles Firebase-specific token access such as FCM.getToken(). Akan uses FCM as the provider, so native apps need both.
@capacitor/push-notifications
Use for notification permission, native registration, notification action/click listener, delivered notifications, and Android notification channels.
@capacitor-community/fcm
Use for Firebase Messaging token access. This keeps Android and iOS server delivery on the same Firebase Admin send({ token }) contract.
Client registration
Call register() from a user-facing action such as a settings toggle or an enable-notifications button. It may ask for permission. After it returns a PushToken, immediately pass that token to your app's storage API.
Client registration
registerPushToken is not an Akan built-in API. It is the app-level API shown below. Name it and shape it to match your user/device domain.
register(): Requests permission when needed and returns a PushToken containing token, platform, provider, and optional deviceId.
App storage: Store the returned PushToken through an app-level user/device API. Akan does not decide where your user domain keeps device credentials.
Click routing: Send a url field from the server. Akan normalizes it into data.url so notification clicks can enter the CSR router.
Manage push tokens in the app DB
Each device's token is managed at the app level, not by Akan. This section explains how to store and manage tokens in a database and how to send notifications using active tokens.
The methods described in this section are examples. Manage tokens in a way that matches your app's structure.
Push token lifecycle
apps/myapp/lib/userDevice/userDevice.constant.ts
apps/myapp/lib/userDevice/userDevice.signal.ts
apps/myapp/ui/PushTokenRegister.tsx
Server send
Cleanup after failed send
ios.teamId: Apple Developer Team ID used for universal link association files.
android.sha256CertFingerprints: Signing certificate fingerprints used by Android app links. Debug builds and release builds usually have different fingerprints.
Android debug SHA-256
  • Enter the same package name as mobile.appId.
  • Download google-services.json.
  • Place it at apps/myapp/public/google-services.json.
  • Copy it into the generated App target and confirm target membership in Xcode.
  • Add permissions: ["push"] to the mobile target. Akan writes the iOS push entitlement, remote-notification background mode, and the AppDelegate bridge needed by Capacitor.
  • Akan sets aps-environment automatically: local, simulator, and debug runs use development; release builds use production.
  • In Apple Developer, prefer creating an APNs auth key from Keys and upload the .p8 key in Firebase Console > Cloud Messaging. If you are in Certificates and only see Apple Push Notification service SSL, that is the certificate-based APNs setup instead.
  • Upload APNs credentials for both development and production in Firebase. Development is required for simulator/debug delivery; production is required for TestFlight and App Store delivery.