app-icon-badge-next 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AdzeB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+<h1 align="center">App Icon Badge Next</h1>
+
+<p align="center">
+  Production-ready app icon badging for modern Expo and React Native workflows.
+</p>
+
+<p align="center">
+  <a href="https://github.com/AdzeB/app-icon-badge-next"><img src="https://img.shields.io/badge/repo-AdzeB%2Fapp--icon--badge--next-181717?style=flat-square&logo=github" alt="repo"></a>
+  <a href="https://www.npmjs.com/package/app-icon-badge-next"><img src="https://img.shields.io/npm/v/app-icon-badge-next.svg?style=flat-square" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/app-icon-badge-next"><img src="https://img.shields.io/npm/dm/app-icon-badge-next.svg?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/AdzeB/app-icon-badge-next/blob/main/LICENSE"><img src="https://img.shields.io/github/license/AdzeB/app-icon-badge-next?style=flat-square" alt="license"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/AdzeB/app-icon-badge-next/stargazers"><img src="https://img.shields.io/github/stars/AdzeB/app-icon-badge-next?style=social" alt="stars"></a>
+  <a href="https://github.com/AdzeB/app-icon-badge-next/network/members"><img src="https://img.shields.io/github/forks/AdzeB/app-icon-badge-next?style=social" alt="forks"></a>
+  <a href="https://github.com/AdzeB/app-icon-badge-next/issues"><img src="https://img.shields.io/github/issues/AdzeB/app-icon-badge-next?style=social" alt="issues"></a>
+</p>
+
+---
+
+## About
+
+`app-icon-badge-next` is the production-ready successor to [`app-icon-badge`](https://github.com/obytes/app-icon-badge), focused on reliability in CI/EAS, support for modern Expo icon models, and predictable results across current iOS and Android launcher behavior.
+
+## Motivation
+
+Mobile teams often install multiple builds of the same app (development, QA, staging, production). When icons look identical, QA and debugging slow down.
+
+`app-icon-badge-next` overlays clear environment/version badges on icons so builds are easy to identify at a glance.
+
+## Features
+
+- Expo config plugin and library API support.
+- Platform-aware badge configuration:
+  - shared `badges`
+  - `ios.badges`
+  - `android.badges`
+- Android adaptive icon safe-zone support (`adaptiveSafeMode`, `android.safeZoneScale`).
+- Badge text controls: `fontScale`, `padding`, `letterSpacing`, `opacity`.
+- Deterministic cache support to skip unchanged generations.
+- Debug and dry-run modes for safer CI usage.
+- Expo 54+ icon model handling (root icon, Android icon + adaptive foreground, iOS string and object variants).
+
+## Installation
+
+```bash
+# yarn
+yarn add app-icon-badge-next
+
+# npm
+npm install app-icon-badge-next
+
+# pnpm
+pnpm add app-icon-badge-next
+```
+
+## Usage
+
+### Expo Plugin
+
+```ts
+// app.config.ts
+import type { ConfigContext, ExpoConfig } from '@expo/config';
+import type { AppIconBadgeConfig } from 'app-icon-badge-next/types';
+
+const VERSION = '1.0.1';
+const APP_ENV = 'QA';
+
+const appIconBadgeConfig: AppIconBadgeConfig = {
+  enabled: true,
+  cache: true,
+  debug: false,
+  dryRun: false,
+  adaptiveSafeMode: true,
+  badges: [
+    {
+      text: APP_ENV,
+      type: 'banner',
+      color: 'white',
+      background: '#FF0000',
+      fontScale: 1,
+      padding: 0,
+      letterSpacing: 0,
+      opacity: 1,
+    },
+  ],
+  ios: {
+    badges: [
+      { text: VERSION, type: 'ribbon', position: 'right' },
+    ],
+  },
+  android: {
+    safeZoneScale: 0.72,
+    badges: [
+      { text: VERSION, type: 'ribbon', position: 'right' },
+    ],
+  },
+};
+
+export default ({ config }: ConfigContext): ExpoConfig => ({
+  ...config,
+  name: 'my-app',
+  icon: './assets/icon.png',
+  android: {
+    icon: './assets/icon-android.png',
+    adaptiveIcon: {
+      foregroundImage: './assets/adaptive-icon.png',
+      backgroundColor: '#FFFFFF',
+    },
+  },
+  plugins: [['app-icon-badge-next', appIconBadgeConfig]],
+});
+```
+
+Plugin option summary (defaults in parentheses):
+
+- `enabled`: enable or disable generation (`true`).
+- `badges`: shared badge layers for all platforms.
+- `ios.badges`: iOS-only badge layers (falls back to `badges`).
+- `android.badges`: Android-only badge layers (falls back to `badges`).
+- `android.safeZoneScale`: safe-zone scale for adaptive foreground, 0.4-1 (`0.72`).
+- `adaptiveSafeMode`: apply safe-zone transform for adaptive icons (`true`).
+- `cache`: deterministic cache for unchanged inputs (`true`).
+- `debug`: structured debug logs (`false`).
+- `dryRun`: skip file writes (`false`).
+
+The plugin rewrites configured icon paths to fixed outputs under `.expo/app-icon-badge` and generates the badged images at that moment (synchronously, before Expo's own icon handling reads them). A deterministic cache keyed on source bytes + badge config makes repeat evaluations no-ops, and the plugin is idempotent when Expo re-applies it to an already rewritten config.
+
+Source: <https://github.com/AdzeB/app-icon-badge-next/blob/main/src/plugin/app.plugin.ts>
+
+### As a Library
+
+```ts
+import { addBadge } from 'app-icon-badge-next';
+import path from 'node:path';
+
+const icon = path.resolve(__dirname, './assets/icon.png');
+
+await addBadge({
+  icon,
+  dstPath: './assets/icon.environment.png',
+  badges: [
+    {
+      text: 'staging',
+      type: 'banner',
+      color: 'white',
+      background: '#FF0000',
+      fontScale: 1,
+      padding: 0,
+      letterSpacing: 0,
+      opacity: 1,
+    },
+    {
+      text: '1.0.1',
+      type: 'ribbon',
+      position: 'right',
+    },
+  ],
+  isAdaptiveIcon: false,
+  adaptiveSafeMode: true,
+  safeZoneScale: 0.72,
+  debug: false,
+  dryRun: false,
+});
+```
+
+All options except `icon` and `badges` are optional. Defaults: `isAdaptiveIcon: false`, `adaptiveSafeMode: true`, `safeZoneScale: 0.72`, `debug: false`, `dryRun: false`. Omitting `dstPath` writes next to the source as `<name>.result.<ext>`.
+
+## CLI
+
+Run the CLI:
+
+```bash
+npx app-icon-badge-next --help
+```
+
+Command help:
+
+```text
+Usage: app-icon-badge-next [options] [command]
+
+Generate app icons with badges
+
+Options:
+  -V, --version                   output the version number
+  -h, --help                      display help for command
+
+Commands:
+  add-badge [options] <iconPath>
+  help [command]                  display help for command
+```
+
+`add-badge` options:
+
+```text
+Usage: app-icon-badge-next add-badge [options] <iconPath>
+
+Options:
+  --text <text>              badge text
+  --type <type>              badge type: banner | ribbon
+  --position <position>      banner: top | bottom, ribbon: left | right
+  --background <background>  badge background as #rrggbb
+  --color <color>            badge text color: white | black (default: "white")
+  --platform <platform>      target platform: ios | android | all (default: "all")
+  --preview                  write result to preview path (default: false)
+  --safe-zone                enable adaptive safe zone (default: false)
+  --scale <scale>            safe zone scale (0.4-1) (default: "0.72")
+  --dry-run                  no file write (default: false)
+  --debug                    debug logs (default: false)
+  -h, --help                 display help for command
+```
+
+Example:
+
+```bash
+npx app-icon-badge-next add-badge ./assets/icon.png \
+  --type banner \
+  --text QA \
+  --position top \
+  --background '#45f4ee' \
+  --color black \
+  --platform all \
+  --safe-zone \
+  --scale 0.72
+```
+
+## Contributing
+
+Contributions are welcome! See the [contributing guide](./.github/CONTRIBUTING.md) for setup, workflow, and release details.
+
+```bash
+pnpm install     # install dependencies
+pnpm type-check  # TypeScript type checking
+pnpm build       # build dist/
+pnpm test        # run tests (requires a prior build)
+```
+
+- Found a bug or want a feature? [Open an issue](https://github.com/AdzeB/app-icon-badge-next/issues/new/choose).
+- Security issue? Report it privately — see the [security policy](./.github/SECURITY.md).
+- This project follows the [Contributor Covenant Code of Conduct](./.github/CODE_OF_CONDUCT.md).
+
+Releases are automated with [Changesets](https://github.com/changesets/changesets); see [CHANGELOG.md](./CHANGELOG.md) for release notes.
+
+## Special Thanks and License Attribution
+
+Special thanks to the original project and maintainers:
+
+- Original library: <https://github.com/obytes/app-icon-badge>
+- Notable upstream fixes and context that influenced this successor:
+  - <https://github.com/obytes/app-icon-badge/pull/44>
+  - <https://github.com/obytes/app-icon-badge/pull/43>
+  - <https://github.com/obytes/app-icon-badge/issues/38>
+  - <https://github.com/obytes/app-icon-badge/issues/37>
+
+License agreement and attribution:
+
+- `app-icon-badge-next` is MIT licensed.
+- The original `obytes/app-icon-badge` project is MIT licensed.
+- This successor preserves attribution to the original work and follows MIT license terms for reuse and distribution.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./dist/app.plugin.js').default;

package/dist/app.plugin.js

@@ -0,0 +1,268 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/plugin/app.plugin.ts
+var app_plugin_exports = {};
+__export(app_plugin_exports, {
+  default: () => app_plugin_default
+});
+module.exports = __toCommonJS(app_plugin_exports);
+var import_node_child_process = require("child_process");
+var import_node_fs3 = __toESM(require("fs"));
+var import_node_os = __toESM(require("os"));
+var import_node_path3 = __toESM(require("path"));
+var import_zod2 = require("zod");
+
+// src/core/validation.ts
+var import_zod = require("zod");
+var hexColor = import_zod.z.string().regex(/^#[0-9a-fA-F]{6}$/);
+var baseBadge = {
+  text: import_zod.z.string().min(1),
+  color: import_zod.z.enum(["white", "black"]).default("white"),
+  background: hexColor.optional(),
+  fontScale: import_zod.z.number().min(0.5).max(2).default(1),
+  letterSpacing: import_zod.z.number().min(0).max(10).default(0),
+  padding: import_zod.z.number().min(0).max(120).default(0),
+  opacity: import_zod.z.number().min(0).max(1).default(1)
+};
+var banner = import_zod.z.object({
+  type: import_zod.z.literal("banner"),
+  position: import_zod.z.enum(["top", "bottom"]).default("bottom"),
+  ...baseBadge
+});
+var ribbon = import_zod.z.object({
+  type: import_zod.z.literal("ribbon"),
+  position: import_zod.z.enum(["left", "right"]).default("right"),
+  ...baseBadge
+});
+var badgeSchema = import_zod.z.discriminatedUnion("type", [banner, ribbon]);
+var addBadgeParamsSchema = import_zod.z.object({
+  icon: import_zod.z.string().min(1),
+  dstPath: import_zod.z.string().optional(),
+  badges: import_zod.z.array(badgeSchema).min(1),
+  isAdaptiveIcon: import_zod.z.boolean().default(false),
+  adaptiveSafeMode: import_zod.z.boolean().default(true),
+  safeZoneScale: import_zod.z.number().min(0.4).max(1).default(0.72),
+  debug: import_zod.z.boolean().default(false),
+  dryRun: import_zod.z.boolean().default(false)
+});
+var pluginOptionsSchema = import_zod.z.object({
+  enabled: import_zod.z.boolean().default(true),
+  badges: import_zod.z.array(badgeSchema).optional(),
+  ios: import_zod.z.object({ badges: import_zod.z.array(badgeSchema).optional() }).default({}),
+  android: import_zod.z.object({
+    badges: import_zod.z.array(badgeSchema).optional(),
+    safeZoneScale: import_zod.z.number().min(0.4).max(1).default(0.72)
+  }).default({}),
+  adaptiveSafeMode: import_zod.z.boolean().default(true),
+  cache: import_zod.z.boolean().default(true),
+  debug: import_zod.z.boolean().default(false),
+  dryRun: import_zod.z.boolean().default(false)
+});
+
+// src/core/cache.ts
+var import_node_fs2 = __toESM(require("fs"));
+var import_node_path2 = __toESM(require("path"));
+
+// src/core/utils.ts
+var import_node_crypto = __toESM(require("crypto"));
+var import_node_fs = __toESM(require("fs"));
+var import_node_path = __toESM(require("path"));
+function sha256(value) {
+  return import_node_crypto.default.createHash("sha256").update(value).digest("hex");
+}
+function resolveFile(projectRoot, maybeRelative) {
+  return import_node_path.default.isAbsolute(maybeRelative) ? maybeRelative : import_node_path.default.join(projectRoot, maybeRelative);
+}
+
+// src/core/cache.ts
+var EMPTY = { version: "1", entries: {} };
+function readCache(projectRoot) {
+  const cachePath = import_node_path2.default.join(projectRoot, ".expo", "app-icon-badge", "cache.json");
+  try {
+    return JSON.parse(import_node_fs2.default.readFileSync(cachePath, "utf8"));
+  } catch {
+    return EMPTY;
+  }
+}
+function isCacheHit(manifest, destination, hash) {
+  return manifest.entries[destination] === hash;
+}
+
+// src/plugin/app.plugin.ts
+var DST_DIR = ".expo/app-icon-badge";
+var iosIconObjectSchema = import_zod2.z.object({
+  light: import_zod2.z.string().optional(),
+  dark: import_zod2.z.string().optional(),
+  tinted: import_zod2.z.string().optional()
+}).catchall(import_zod2.z.unknown());
+function iosIconObject(config) {
+  const icon = config.ios?.icon;
+  if (!icon || typeof icon !== "object") return void 0;
+  const parsed = iosIconObjectSchema.safeParse(icon);
+  return parsed.success ? parsed.data : void 0;
+}
+function setIosIcon(config, icon) {
+  const iosWithIcon = { ...config.ios, icon };
+  config.ios = iosWithIcon;
+}
+function debugLog(enabled, payload) {
+  if (!enabled) return;
+  process.stdout.write(`[app-icon-badge-next:plugin] ${JSON.stringify(payload)}
+`);
+}
+function iconTargets(options) {
+  const shared = options.badges ?? [];
+  const ios = options.ios.badges ?? shared;
+  const android = options.android.badges ?? shared;
+  return [
+    {
+      destination: `${DST_DIR}/icon.png`,
+      badges: shared,
+      get: (c) => typeof c.icon === "string" ? c.icon : void 0,
+      set: (c, destination) => {
+        c.icon = destination;
+      }
+    },
+    {
+      destination: `${DST_DIR}/android-icon.png`,
+      badges: android,
+      get: (c) => typeof c.android?.icon === "string" ? c.android.icon : void 0,
+      set: (c, destination) => {
+        c.android = { ...c.android, icon: destination };
+      }
+    },
+    {
+      destination: `${DST_DIR}/android-adaptive-foreground.png`,
+      badges: android,
+      adaptive: true,
+      get: (c) => typeof c.android?.adaptiveIcon?.foregroundImage === "string" ? c.android.adaptiveIcon.foregroundImage : void 0,
+      set: (c, destination) => {
+        c.android = {
+          ...c.android,
+          adaptiveIcon: { ...c.android?.adaptiveIcon, foregroundImage: destination }
+        };
+      }
+    },
+    {
+      destination: `${DST_DIR}/ios-icon.png`,
+      badges: ios,
+      get: (c) => typeof c.ios?.icon === "string" ? c.ios.icon : void 0,
+      set: (c, destination) => {
+        setIosIcon(c, destination);
+      }
+    },
+    ...["light", "dark", "tinted"].map(
+      (variant) => ({
+        destination: `${DST_DIR}/ios-icon-${variant}.png`,
+        badges: ios,
+        get: (c) => iosIconObject(c)?.[variant],
+        set: (c, destination) => {
+          setIosIcon(c, { ...iosIconObject(c), [variant]: destination });
+        }
+      })
+    )
+  ];
+}
+function runGeneration(payload) {
+  const payloadPath = import_node_path3.default.join(
+    import_node_os.default.tmpdir(),
+    `app-icon-badge-next-${process.pid}-${Date.now()}.json`
+  );
+  import_node_fs3.default.writeFileSync(payloadPath, JSON.stringify(payload));
+  try {
+    (0, import_node_child_process.execFileSync)(process.execPath, [require.resolve("./generate.js"), payloadPath], {
+      stdio: ["ignore", "inherit", "inherit"]
+    });
+  } finally {
+    import_node_fs3.default.rmSync(payloadPath, { force: true });
+  }
+}
+var withIconBadge = (config, options = {}) => {
+  const parsed = pluginOptionsSchema.parse(options);
+  if (!parsed.enabled) return config;
+  const projectRoot = config._internal?.projectRoot ?? process.cwd();
+  const manifest = readCache(projectRoot);
+  const jobs = [];
+  for (const target of iconTargets(parsed)) {
+    if (target.badges.length === 0) continue;
+    const source = target.get(config);
+    if (!source) continue;
+    if (source.startsWith(DST_DIR)) continue;
+    const sourceAbsolute = resolveFile(projectRoot, source);
+    if (!import_node_fs3.default.existsSync(sourceAbsolute)) {
+      debugLog(parsed.debug, { event: "missing-source", source });
+      continue;
+    }
+    target.set(config, target.destination);
+    const cachePayload = {
+      badges: target.badges,
+      isAdaptiveIcon: target.adaptive ?? false,
+      adaptiveSafeMode: parsed.adaptiveSafeMode,
+      safeZoneScale: parsed.android.safeZoneScale,
+      source: sourceAbsolute
+    };
+    const hash = sha256(
+      Buffer.concat([import_node_fs3.default.readFileSync(sourceAbsolute), Buffer.from(JSON.stringify(cachePayload))])
+    );
+    const destinationAbsolute = import_node_path3.default.join(projectRoot, target.destination);
+    if (parsed.cache && isCacheHit(manifest, target.destination, hash) && import_node_fs3.default.existsSync(destinationAbsolute)) {
+      debugLog(parsed.debug, { event: "cache-hit", destination: target.destination });
+      continue;
+    }
+    jobs.push({
+      icon: sourceAbsolute,
+      dstPath: destinationAbsolute,
+      destination: target.destination,
+      hash,
+      badges: target.badges,
+      isAdaptiveIcon: target.adaptive ?? false
+    });
+  }
+  if (jobs.length > 0 && !parsed.dryRun) {
+    runGeneration({
+      projectRoot,
+      cache: parsed.cache,
+      debug: parsed.debug,
+      adaptiveSafeMode: parsed.adaptiveSafeMode,
+      safeZoneScale: parsed.android.safeZoneScale,
+      jobs
+    });
+  }
+  debugLog(parsed.debug, {
+    event: "config-updated",
+    generated: jobs.map((job) => job.destination),
+    adaptiveSafeMode: parsed.adaptiveSafeMode,
+    safeZoneScale: parsed.android.safeZoneScale,
+    cache: parsed.cache,
+    dryRun: parsed.dryRun
+  });
+  return config;
+};
+var app_plugin_default = withIconBadge;