@molecule/app-platform

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Platform detection and abstraction for molecule.dev.

Detects the current runtime (web, iOS, Android, Electron/desktop) by inspecting Capacitor / Electron / React Native markers, and provides platform-branching helpers ({@link onPlatform}, {@link isPlatform}) plus a native-startup coordinator ({@link createCapacitorApp}). Pure functions — no bond wiring required.

Quick Start

import { isPlatform, onPlatform, platform } from '@molecule/app-platform'

const info = platform() // cached PlatformInfo
if (info.isNative) initNativePlugins()

const label = onPlatform({
  ios: () => 'App Store',
  android: () => 'Play Store',
  default: () => 'Web', // `default` is required — always a fallback
})

Type

core

Installation

npm install @molecule/app-platform @molecule/app-lifecycle @molecule/app-logger @molecule/app-push

API

Interfaces

CapacitorApp

Capacitor app coordinator return type.

interface CapacitorApp {
  /**
   * Initialize the app. Call this during startup.
   */
  initialize(): Promise<void>

  /**
   * Whether the app is fully ready.
   */
  isReady(): boolean

  /**
   * Get the current initialization state.
   */
  getState(): CapacitorAppState

  /**
   * Subscribe to state changes.
   */
  subscribe(callback: (state: CapacitorAppState) => void): () => void

  /**
   * Register a callback for when the app becomes ready.
   * If already ready, the callback fires immediately.
   */
  onReady(callback: () => void): () => void

  /**
   * Clean up listeners.
   */
  destroy(): void
}

CapacitorAppOptions

Capacitor app configuration options.

interface CapacitorAppOptions {
  /**
   * Callback invoked when the app is fully initialized and ready to render.
   */
  onReady?: () => void | Promise<void>

  /**
   * Whether to initialize push notifications on startup.
   * @default false
   */
  pushNotifications?: boolean

  /**
   * Whether to handle deep links on startup.
   * @default false
   */
  deepLinks?: boolean

  /**
   * Deep link handler callback.
   */
  onDeepLink?: (url: string) => void
}

CapacitorAppState

Capacitor app coordinator state.

interface CapacitorAppState {
  /**
   * Whether the app is fully initialized.
   */
  ready: boolean

  /**
   * Whether device ready has fired.
   */
  deviceReady: boolean

  /**
   * Whether push notifications are initialized.
   */
  pushReady: boolean

  /**
   * Initialization error, if any.
   */
  error: Error | null
}

PlatformInfo

Detected runtime environment details (platform, native/mobile/desktop/web flags, dev/prod mode).

interface PlatformInfo {
  /**
   * The current platform.
   */
  platform: Platform

  /**
   * Whether running in a native app (Capacitor, React Native, Electron).
   */
  isNative: boolean

  /**
   * Whether running in a mobile app (iOS or Android).
   */
  isMobile: boolean

  /**
   * Whether running in a desktop app (Electron, macOS, Windows, Linux).
   */
  isDesktop: boolean

  /**
   * Whether running in a web browser.
   */
  isWeb: boolean

  /**
   * Whether running in development mode.
   */
  isDevelopment: boolean

  /**
   * Whether running in production mode.
   */
  isProduction: boolean

  /**
   * The user agent string (if available).
   */
  userAgent?: string

  /**
   * The app version (if available).
   */
  appVersion?: string
}

Types

Platform

Target runtime platforms: web, ios, android, electron, macos, windows, linux.

type Platform = 'web' | 'ios' | 'android' | 'electron' | 'macos' | 'windows' | 'linux'

Functions

createCapacitorApp(options)

Creates a Capacitor app coordinator.

Orchestrates native app initialization in the correct order:

1. Wait for device ready
2. Initialize push notifications (if configured)
3. Handle deep links (if configured)
4. Signal readiness

function createCapacitorApp(options?: CapacitorAppOptions): CapacitorApp

• options — Configuration options.

Returns: A CapacitorApp instance with lifecycle, push notification, and deep link management.

detectPlatform()

Detects the current runtime platform by checking for Capacitor, Electron, React Native, and falling back to 'web'.

function detectPlatform(): Platform

Returns: The detected platform identifier.

getPlatformInfo(env)

Builds comprehensive platform information including platform type, environment flags, and user agent details.

function getPlatformInfo(env?: { isDevelopment?: boolean; isProduction?: boolean }): PlatformInfo

• env — Optional environment overrides for development/production flags.
• env.isDevelopment — Override for development mode detection.
• env.isProduction — Override for production mode detection.

Returns: A PlatformInfo object with all platform details.

isPlatform(platforms)

Checks if the current platform matches any of the specified platforms.

function isPlatform(platforms?: Platform[]): boolean

• platforms — One or more platform identifiers to check against.

Returns: true if the current platform matches any of the given platforms.

onPlatform(handlers)

Executes a platform-specific handler based on the detected platform. Falls back to the default handler if no handler matches.

function onPlatform(handlers: Partial<Record<Platform, () => T>> & { default: () => T }): T

• handlers — A map of platform identifiers to handler functions, with a required default.

Returns: The return value of the matched (or default) handler.

platform()

Returns the current platform info, caching the result after first call.

function platform(): PlatformInfo

Returns: The cached PlatformInfo object.

resetPlatformCache()

Resets the cached platform info. Useful for testing or when the platform context changes.

function resetPlatformCache(): void

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-lifecycle ^1.0.1
• @molecule/app-logger ^1.0.1
• @molecule/app-push ^1.0.1

Runtime Dependencies

• @molecule/app-lifecycle

• @molecule/app-logger

• @molecule/app-push

• A mobile BROWSER is 'web', not 'ios'/'android'. isMobile means "running as a native mobile app" — Safari on an iPhone reports platform: 'web', isMobile: false. Use CSS media queries / viewport checks for responsive layout; use this package only for CAPABILITY branching (native plugins, file paths, store links, push setup).

• Branch through {@link onPlatform}/{@link isPlatform}, never by parsing navigator.userAgent yourself — hand-rolled UA sniffing is exactly what this package exists to replace.

• {@link platform} caches after the first call; call {@link resetPlatformCache} in tests or when the runtime context changes.