API reference#

export function defineLynxConfig(config: LynxConfig): LynxConfig

export function resolveConfig(raw: LynxConfig): ResolvedConfig

export function modulesForPlatform(config: ResolvedConfig, platform: Platform): ResolvedModule[]

export function resolveAssets(
    raw: LynxConfig,
    cwd: string
): { ios: ResolvedIosAssets; android: ResolvedAndroidAssets }

export function validateManifest(manifest: unknown): string[]

export function linkAndroid(
    config: ResolvedConfig,
    manifests: ModuleManifest[]
): AndroidLinkResult

export function linkIos(
    config: ResolvedConfig,
    manifests: ModuleManifest[]
): IosLinkResult

export async function runPrebuild(opts: PrebuildOptions = {}): Promise<void>

export async function loadConfig(cwd: string): Promise<LynxConfig>

export async function loadManifests(modulePackages: string[], cwd: string): Promise<ModuleManifest[]>

export async function startDevServer(opts: DevServerOptions): Promise<void>

export async function runDoctor(cwd: string, logger: Logger): Promise<void>

export function generateQR(text: string, opts?: { quiet?: number; invert?: boolean }): string

export function getLanIP(): string | null

export function getAllLanIPs(): { name: string; address: string }[]

export function getDeviceStatus(appId?: string, iosBundleId?: string): DeviceStatus

export function listAndroidDevices(): AndroidDevice[]

export function isAdbAvailable(): boolean

export function isLynxGoInstalled(deviceId: string): boolean

export function launchLynxGo(deviceId: string, url: string): boolean

export default definePlugin({
    name: 'lynx',
    detect: isLynxProject,
    commands: {
        dev, build, doctor, outdated, upgrade, add, remove,
        prebuild, 'run:android', 'run:ios',
    },
})

export interface LynxConfig {
    name: string;
    version?: string;
    buildNumber?: string;            // default '1'
    icon?: string;                   // 1024x1024 PNG, falls back to bundled default
    splash?: SplashConfig;
    scheme?: string;                 // deep-link URL scheme
    orientation?: Orientation;       // default 'portrait'
    modules?: (string | ModuleConfig)[]; // per-module overrides; installed modules auto-link
    excludeModules?: string[];
    iconSets?: IconSetConfig[];
    android?: AndroidConfig;
    ios?: IosConfig;
    platforms?: Platform[];          // defaults to both
    prebuild?: PrebuildHooksConfig;
    variants?: Record<string, VariantConfig>; // per-environment app identity
}

export interface VariantConfig extends DeepPartial<Omit<LynxConfig, 'variants'>> {
    extends?: string;        // inherit another variant first
    idSuffix?: string;       // appended to applicationId / bundleIdentifier
    nameSuffix?: string;     // appended to the display name
    schemeSuffix?: string;   // appended to the deep-link scheme
    release?: boolean;       // treat as a release build (default false)
    iconBadge?: string | false; // launcher-icon badge label (auto for non-release)
}

export type Platform = 'android' | 'ios';

export type Orientation = 'portrait' | 'landscape' | 'all' | 'default';

export type PlistValue = boolean | number | string | PlistValue[] | { [key: string]: PlistValue };

export type IconMode = 'svg' | 'font';

export type IconStyle = 'solid' | 'regular' | 'brands' | 'light' | 'thin' | 'duotone';

export interface IconSetConfig {
    id: string;            // call-site alias, unique
    source: string;        // adapter npm package, e.g. '@sigx/lynx-icons-fa-free'
    styles?: IconStyle[];  // FA only
    mode?: IconMode;       // default 'font' if adapter ships TTF else 'svg'
    include?: string[];    // force-include glyphs; ['*'] ships full catalog
}

export interface ModuleConfig {
    package: string;                 // e.g. '@sigx/lynx-camera'
    platforms?: Platform[];          // omit = all
    config?: Record<string, unknown>;// passed to native auto-linker
    disabled?: boolean;              // skip linking even though installed
}

export type SplashResizeMode = 'contain' | 'cover' | 'center';

export interface SplashConfig {
    image?: string;
    backgroundColor?: string;        // default '#FFFFFF'
    resizeMode?: SplashResizeMode;   // default 'center'; iOS treats 'cover' as 'contain'
    dark?: SplashDarkConfig;
}

export interface SplashDarkConfig {
    image?: string;            // falls back to light image
    backgroundColor?: string;  // falls back to light background
}

export interface AdaptiveIconConfig {
    foreground: string;        // 1024x1024, logo in inner 66% safe zone
    backgroundColor?: string;  // default '#FFFFFF'
    monochrome?: string;       // Android 13+ themed icon <monochrome> layer
}

export interface IosIconConfig {
    light: string;   // 1024x1024 PNG
    dark?: string;   // opaque recommended
    tinted?: string; // grayscale source the system tints
}

export interface AndroidFeatureConfig {
    name: string;       // e.g. 'android.hardware.camera'
    required?: boolean; // default false
}

export interface AndroidConfig {
    applicationId?: string;
    minSdk?: number;       // default 24
    targetSdk?: number;    // default 35
    compileSdk?: number;   // default 35
    versionCode?: number;  // default 1
    dependencies?: string[];
    permissions?: string[];
    features?: AndroidFeatureConfig[];
    googleMapsApiKey?: string;
    manifestMetaData?: Record<string, string>;     // arbitrary <meta-data> entries
    applicationAttributes?: Record<string, string | boolean | number>; // arbitrary <application> attrs
    googleServicesFile?: string;                   // Firebase google-services.json, copied into android/app/ each prebuild
    icon?: string;
    adaptiveIcon?: AdaptiveIconConfig;
    notificationIcon?: string;
    notificationColor?: string;
    splash?: SplashConfig;
    scheme?: string;
    orientation?: Orientation;
}

export interface IosConfig {
    bundleIdentifier?: string;
    deploymentTarget?: string;            // default '15.0'
    buildNumber?: string;                 // CFBundleVersion, default '1'
    developmentTeam?: string;             // Apple Team ID -> DEVELOPMENT_TEAM
    codeSignStyle?: 'Automatic' | 'Manual';
    supportsTablet?: boolean;             // default true (TARGETED_DEVICE_FAMILY '1,2')
    requiresFullScreen?: boolean;         // default false
    pods?: Record<string, string>;
    usageDescriptions?: Record<string, string>;
    bgTaskIdentifiers?: string[];
    infoPlist?: Record<string, PlistValue>;        // arbitrary Info.plist keys, merged last-write-wins
    usesNonExemptEncryption?: boolean;             // convenience for ITSAppUsesNonExemptEncryption
    entitlements?: Record<string, PlistValue>;     // app-level code-signing entitlements (counterpart to infoPlist)
    icon?: string | IosIconConfig;
    splash?: SplashConfig;
    scheme?: string;
    orientation?: Orientation;
}

export interface PrebuildHooksConfig {
    // Path to a .mjs/.js/.cjs module run after managed native files are rendered
    // and auto-linking is done. Default export, if a function, is awaited with
    // { cwd, config, platforms }.
    post?: string;
}

export interface ResolvedConfig {
    name: string;
    version: string;
    buildNumber: string;
    modules: ResolvedModule[];
    excludeModules: string[];
    iconSets: ResolvedIconSet[];
    platforms: Platform[];
    android: Required<Pick<NonNullable<LynxConfig['android']>,
        'minSdk' | 'targetSdk' | 'compileSdk' | 'versionCode'>>
        & Omit<NonNullable<LynxConfig['android']>,
        'minSdk' | 'targetSdk' | 'compileSdk' | 'versionCode'>;
    ios: Required<Pick<NonNullable<LynxConfig['ios']>,
        'deploymentTarget' | 'buildNumber'>>
        & Omit<NonNullable<LynxConfig['ios']>,
        'deploymentTarget' | 'buildNumber'>;
    prebuild?: LynxConfig['prebuild'];
}

export interface ResolvedModule {
    package: string;
    platforms: Platform[];
    config: Record<string, unknown>;
    disabled: boolean;
}

export interface ResolvedIconSet {
    id: string;
    source: string;
    styles: IconStyle[] | null;
    mode: IconMode | null;
    include: string[];
}

export interface ResolvedPlatformAssets {
    iconSource: string;
    splashImage: string;
    splashBackground: string;
    splashResizeMode: SplashResizeMode;
    splashDark: { image: string; backgroundColor: string } | null;
    scheme: string | null;
    orientation: Orientation;
}

export interface ResolvedIosAssets extends ResolvedPlatformAssets {
    iconDark: string | null;
    iconTinted: string | null;
}

export interface ResolvedAndroidAssets extends ResolvedPlatformAssets {
    adaptiveIcon: { foreground: string; backgroundColor: string; monochrome: string | null } | null;
    notificationIcon: string | null;
    notificationColor: string | null;
}

export interface ModuleManifest {
    name: string;        // bridge name in NativeModules
    package: string;
    description: string;
    type?: 'module' | 'dev-client';
    platforms: ('android' | 'ios')[];
    android?: AndroidManifest;
    ios?: IosManifest;
}

export interface AndroidManifest {
    moduleClass?: string;
    publisherClass?: string;
    activityHook?: ActivityHookManifest;
    initClass?: string;
    sourceDir?: string;
    releaseStubsDir?: string;
    debugOnly?: boolean;
    dependencies?: string[];
    permissions?: string[];
    features?: AndroidFeatureEntry[];
    gradlePlugins?: AndroidGradlePluginEntry[];  // Gradle plugins applied to app/build.gradle.kts
    minSdk?: number;
    services?: AndroidServiceEntry[];
    behaviors?: AndroidBehaviorEntry[];
    metaData?: AndroidMetaDataEntry[];
}

export interface IosManifest {
    moduleClass?: string;
    publisherClass?: string;
    appDelegateHook?: IosAppDelegateHookManifest;
    initClass?: string;
    sourceDir?: string;
    debugOnly?: boolean;
    methods?: string[];
    pods?: Record<string, string>;
    usageDescriptions?: Record<string, string>;
    backgroundModes?: string[];
    bgTaskIdentifiers?: string[];
    uiComponents?: IosUiComponentEntry[];
    entitlements?: Record<string, PlistValue>;  // code-signing entitlements aggregated into the app's .entitlements
    deploymentTarget?: string;
}

export interface AndroidMetaDataEntry {
    name: string;
    value?: string;     // literal, highest precedence
    valueFrom?: string; // dotted path into resolved config, e.g. 'android.googleMapsApiKey'
    default?: string;   // fallback
    helpUrl?: string;
}

export interface AndroidBehaviorEntry {
    name: string;          // JSX tag
    behaviorClass: string; // FQ Kotlin class extending com.lynx.tasm.behavior.Behavior
}

export interface AndroidFeatureEntry {
    name: string;
    required?: boolean; // default false
}

export interface AndroidGradlePluginEntry {
    id: string;         // e.g. 'com.google.gms.google-services'
    version: string;    // e.g. '4.4.2'
    requires?: string;  // app-supplied config that must resolve first, e.g. 'android.googleServicesFile'
}

export interface AndroidServiceEntry {
    name: string;        // FQ service class
    exported?: boolean;  // default false
    actions?: string[];  // each becomes one intent-filter action
}

export type AndroidActivityHookMethod =
    | 'onCreate' | 'onResume' | 'onPause'
    | 'onNewIntent' | 'onBackPressed' | 'onRequestPermissionsResult';

export interface ActivityHookManifest {
    class: string; // FQ Kotlin object (singleton)
    methods: AndroidActivityHookMethod[];
}

export interface IosUiComponentEntry {
    name: string;    // JSX tag
    uiClass: string; // Swift class extending LynxUI<UIView>
}

export type IosAppDelegateHookMethod =
    | 'didFinishLaunching' | 'openURL' | 'continueUserActivity'
    | 'didRegisterForRemoteNotificationsWithDeviceToken'
    | 'didFailToRegisterForRemoteNotificationsWithError';

export interface IosAppDelegateHookManifest {
    class: string; // Swift class/enum name
    methods: IosAppDelegateHookMethod[];
}

export interface AndroidLinkResult {
    registryCode: string;
    lifecycleCode: string;
    activityHooksCode: string;
    behaviorsCode: string;
    linkedBehaviors: string[];
    gradleDependencies: string[];
    debugGradleDependencies: string[];
    permissions: string[];
    debugPermissions: string[];
    features: AndroidFeatureEntry[];
    services: AndroidServiceEntry[];
    metaData: ResolvedAndroidMetaData[];
    metaDataWarnings: string[];
    linkedModules: string[];
    linkedLifecyclePublishers: string[];
    lifecyclePublishers: AndroidLifecyclePublisherInfo[];
    linkedActivityHooks: string[];
    devClient?: DevClientInfo;
}

export interface IosLinkResult {
    podfileEntries: string[];
    debugPodfileEntries: string[];
    usageDescriptions: Record<string, string>;
    debugUsageDescriptions: Record<string, string>;
    backgroundModes: string[];
    bgTaskIdentifiers: string[];
    registryCode: string;
    lifecycleCode: string;
    appDelegateHooksCode: string;
    componentRegistryCode: string;
    linkedComponents: string[];
    linkedModules: string[];
    linkedLifecyclePublishers: string[];
    lifecyclePublishers: IosLifecyclePublisherInfo[];
    linkedAppDelegateHooks: string[];
    devClient?: IosDevClientInfo;
}

export interface PrebuildOptions {
    android?: boolean; // default true
    ios?: boolean;     // default true
    clean?: boolean;   // bypass fingerprint fast-path
    cwd?: string;      // default process.cwd()
}

export interface DevServerOptions {
    cwd: string;
    port?: string | number;  // default 8788
    host?: boolean;
    logger: Logger;
    launchAppId?: string;    // Android applicationId to auto-launch w/ dev URL
    launchBundleId?: string; // iOS bundleId to auto-launch on booted sims
    iosSimulatorName?: string;
    selectedTargets?: unknown; // explicit picker/flag target list
    verbose?: boolean;
    disableDeviceLogs?: boolean;
    // ...additional fields
}

export interface AndroidDevice {
    id: string;
    type: 'device' | 'emulator' | 'offline';
    model?: string;
}

export interface IosSimulator {
    udid: string;
    name: string;
    state: string;
    runtime: string;
}

export interface IosDevice {
    udid: string;       // devicectl identifier
    name: string;
    model?: string;
    osVersion?: string;
    transport?: string; // 'wired' | 'wireless'
}

export interface DeviceStatus {
    devices: AndroidDevice[];
    lynxGoInstalled: Map<string, boolean>;
    appInstalled?: Map<string, boolean>;
    adbAvailable: boolean;
    iosSimulators: IosSimulator[];
    xcrunAvailable: boolean;
    iosAppInstalled?: Map<string, boolean>;
    iosDevices: IosDevice[];
    devicectlAvailable: boolean;
    iosDeviceAppInstalled?: Map<string, boolean>;
}