lynxjs-app-config-plugin

Rsbuild plugin to inject application icons, permissions and minimal app config changes into Android / iOS project folders.

Install

For local development inside the monorepo you can link the package; to install normally:

pnpm add -D lynxjs-app-config-plugin

Usage

Import the plugin and provide a top-level options object with android and/or ios platform configs. Each platform is handled independently — you can provide only android or only ios if you wish; the plugin will apply the available platform's changes.

import { pluginLynxAppConfig } from "lynxjs-app-config-plugin";
import { defineConfig } from "@lynx-js/rspeedy";

export default defineConfig({
  plugins: [
    pluginLynxAppConfig({
      android: {
        icon: { path: "./assets/my-android-icon.png" },
        permission: ["android.permission.CAMERA"],
        appConfig: { bundle: "com.example.android", compileSdk: 34 },
      },
      ios: {
        icon: { path: "./assets/my-ios-icon.png" },
        permission: ["NSCameraUsageDescription"],
        appConfig: { bundle: "com.example.ios" },
      },
    }),
  ],
});

API / Options

Top-level options is a LynxAppOptions object with optional android and ios platform configs. Each platform object uses the following shape (see src/utils/schema.ts for TypeScript types):

• android?: {

  • icon: { path: string; foregroundImage?: string; backgroundImage?: string; backgroundColor?: string; foregroundColor?: string; paddingRatio?: number; projectRoot?: string }
  • permission?: string | string[] // Android permission constants (e.g. android.permission.CAMERA)
  • appConfig?: { bundle?: string; scheme?: string; compileSdk?: number; minSdk?: number; targetSdk?: number; versionCode?: number; versionName?: string; name?: string } }

• ios?: {

  • icon: { path: string; foregroundImage?: string; backgroundImage?: string; backgroundColor?: string; foregroundColor?: string; paddingRatio?: number; projectRoot?: string }
  • permission?: string | string[] // iOS plist keys (e.g. NSCameraUsageDescription)
  • appConfig?: { bundle?: string; scheme?: string; version?: string; name?: string } }

Example JavaScript object for options:

const lynxOptions = {
  android: {
    icon: {
      path: "./assets/my-android-icon.png",
      foregroundImage: "./assets/foreground.png",
      backgroundImage: "./assets/background.png",
      backgroundColor: "#ffffff",
      foregroundColor: "#000000",
      paddingRatio: 0.2, // fractional padding for adaptive icons
    },
    permission: [
      "android.permission.CAMERA",
      "android.permission.RECORD_AUDIO",
    ],
    appConfig: {
      bundle: "com.example.android",
      compileSdk: 34,
      minSdk: 21,
      targetSdk: 34,
      versionCode: 2,
      versionName: "1.1.0",
      name: "ExampleAndroid",
    },
  },
  ios: {
    icon: {
      path: "./assets/my-ios-icon.png",
      backgroundColor: "#ffffff",
    },
    permission: ["NSCameraUsageDescription"],
    appConfig: {
      bundle: "com.example.ios",
      scheme: "example",
      version: "1.1.0",
      name: "ExampleIos",
    },
  },
};

export default lynxOptions;

Icon options (common fields)

• path (string): required path to the source icon file used by the platform generator.
• foregroundImage / backgroundImage (string): optional separate images for foreground/background composition.
• backgroundColor / foregroundColor (string): CSS hex or rgba color strings used when composing icons.
• paddingRatio (number): fractional padding for adaptive icons (0..1).
• projectRoot (string): optional override for where to resolve project files when generating iOS icons.

Permissions

You can pass Android permission strings (for example android.permission.CAMERA) or iOS Info.plist keys (for example NSCameraUsageDescription). The plugin will try to add missing entries to AndroidManifest.xml and Info.plist respectively.

• Behavior

• The plugin runs during onBeforeBuild and performs platform-specific steps independently (permissions, app config updates, icon generation). Provide whichever platform configs you need — Android and iOS are applied separately and do not depend on each other.

• For Android the plugin will:

  • find the Android res directory, remove old adaptive drawables, generate mipmap/png icons and write adaptive XML/drawable wrappers (using the generateAndroidIcons utility).
  • update AndroidManifest.xml permissions and optionally apply appConfig edits to the app build.gradle and settings.gradle files.

• For iOS the plugin will:

  • find an AppIcon.appiconset (or use projectRoot to locate Assets), generate icons and update or write Contents.json inside the icon set (using generateIosAppIcons).
  • update Info.plist entries for bundle id and add permission keys where missing.

Limitations & next steps

• The current generators will compose icons and write wrappers, but do not perform a full set of resized assets for every platform variant in all edge cases. The codebase already uses sharp in the utilities and can be extended to produce all required sizes and masks.
• Platform support: Android behavior and file edits (icons, manifest, build.gradle, resource updates) have been tested locally. iOS support (Info.plist edits, xcproject changes, icon writing) is present but has not been exhaustively tested in this repository — contributions and testing on real Xcode projects are welcome.

Contributing

• Contributions, fixes and additional platform tests are welcome. If you find issues with iOS handling or want broader activity filename coverage on Android (different activity class names or packages), please open an issue or submit a PR with reproducer steps and tests.

License: MIT