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 ios platform configs. Note: the plugin currently expects both android and ios top-level configs to be present; if either is missing the plugin will no-op during build.

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). However, the plugin currently requires both android and ios top-level configs to be present; if either is missing it will return early and do nothing. This is intentional to avoid partially-applied plugin runs in some setups.
• 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.
• The plugin currently requires both android and ios configs to be present; if you need one-platform-only behavior at build time you can either pass an empty object for the other platform or call the utilities directly from a script.

License: MIT