{"id":18488123,"url":"https://github.com/obytes/app-icon-badge","last_synced_at":"2025-04-04T17:08:55.656Z","repository":{"id":180692796,"uuid":"616931217","full_name":"obytes/app-icon-badge","owner":"obytes","description":"🧩 Expo plugin/library to add badges for your app icon: banner, ribbon, and fully customizable.","archived":false,"fork":false,"pushed_at":"2023-09-04T21:12:12.000Z","size":5522,"stargazers_count":236,"open_issues_count":2,"forks_count":3,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-04-14T04:37:49.210Z","etag":null,"topics":["android","app-icon","badge-generator","expo","expo-plugin","ios","react-native"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/obytes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-21T11:27:40.000Z","updated_at":"2024-04-10T18:47:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"8be1f542-152c-4856-ab72-7268347e2b0e","html_url":"https://github.com/obytes/app-icon-badge","commit_stats":null,"previous_names":["obytes/app-icon-badge"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obytes%2Fapp-icon-badge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obytes%2Fapp-icon-badge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obytes%2Fapp-icon-badge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obytes%2Fapp-icon-badge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/obytes","download_url":"https://codeload.github.com/obytes/app-icon-badge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217184,"owners_count":20903009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","app-icon","badge-generator","expo","expo-plugin","ios","react-native"],"created_at":"2024-11-06T12:51:18.208Z","updated_at":"2025-04-04T17:08:55.611Z","avatar_url":"https://github.com/obytes.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"App Icon Badge\" src=\"https://github.com/obytes/react-native-template-obytes/assets/11137944/944a6159-7d81-4793-a74a-43c673733bb3\"   /\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003e\nApp Icon Badge\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n✨ Easily generate icons with environment and version badges for your Mobile application. ✨\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/app-icon-badge\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/app-icon-badge.svg?style=flat-square\" alt=\"version\"\u003e\u003c/a\u003e\n  \u003ca href=\"http://www.npmtrends.com/app-icon-badge\"\u003e\u003cimg src=\"https://img.shields.io/npm/dt/app-icon-badge.svg?style=flat-square\" alt=\"downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/yjose/app-icon-badge/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/app-icon-badge.svg?style=flat-square\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"#contributors\"\u003e\u003cimg src=\"https://img.shields.io/badge/all_contributors-16-orange.svg?style=flat-square\" alt=\"All Contributors\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/obytes/app-icon-badge/watchers\"\u003e\u003cimg src=\"https://img.shields.io/github/watchers/obytes/app-icon-badge.svg?style=social\" alt=\"Watch on GitHub\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/obytes/app-icon-badge/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/obytes/app-icon-badge.svg?style=social\" alt=\"Star on GitHub\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://twitter.com/intent/tweet?text=Check%20out%20app-icon-badge%20by%20%40Obytes%20https%3A%2F%2Fgithub.com%2Fobytes%2Fapp-icon-badge%20%F0%9F%91%8D\"\u003e\u003cimg src=\"https://img.shields.io/twitter/url/https/github.com/obytes/app-icon-badge.svg?style=social\" alt=\"Tweet\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003chr/\u003e\n\n## 🚀 Motivation\n\nDuring the development of a mobile application, we typically generate different applications based on the environment (staging, development, production).\n\nHowever, it starts getting confusing when we install all of them on our device, especially if they have the same icon and name. In addition to that, it is difficult for our testers to trace bugs not knowing which version of the application they are using.\n\nTherefore, we need a way to differentiate the applications based on the environment and version. This library generates a badge with the environment and version information and adds it to the app icon.\n\n## 📱 Features\n\n- 🙌 Easy to use as an Expo plugin or a simple library.\n- 📱 Supports universal icons and adaptive icons.\n- 🧩 Supports multiple badges.\n- 🎨 Fully customizable; you can change the badge text, color, background, and position.\n\n## 📦 Installation\n\nInstall the package.\n\n```bash\n## Using yarn\nyarn add app-icon-badge\n## Using npm\nnpm install app-icon-badge\n## Using pnpm\npnpm add app-icon-badge\n```\n\n## 🛠️ Usage\n\n### Expo Plugin\n\nAs we mentioned above, we built the package to be used in Expo projects and generate icons that will be provided to the `icon` and `android.adaptiveIcon.foregroundImage` properties in `app.json`. So, we recommend following the [official Expo documentation](https://docs.expo.dev/develop/user-interface/app-icons) to generate the icons.\n\nTo use the plugin, you need to add it to your `app.config.js` file.\n\n```typescript\n// app.config.ts\nimport type { ConfigContext, ExpoConfig } from '@expo/config';\nimport type { AppIconBadgeConfig } from 'app-icon-badge/types';\n\nconst VERSION = '1.0.1';\nconst APP_ENV = 'QA';\n\nconst appIconBadgeConfig: AppIconBadgeConfig = {\n  enabled: true, // enable/ disable the plugin based on the environment (usually disabled for production builds)\n  badges: [\n    {\n      text: APP_ENV, // banner text\n      type: 'banner', // banner or ribbon\n      color: 'white', // by default it will be white and the only color supported for now is white and black\n      background: '#FF0000', // by default it will be black and we are only supporting hex format for colors\n    },\n    {\n      text: VERSION,\n      type: 'ribbon',\n    },\n  ],\n};\n\nexport default ({ config }: ConfigContext): ExpoConfig =\u003e ({\n  ...config,\n  name: 'my-app',\n  icon: './assets/icon.png',\n  android: {\n    adaptiveIcon: {\n      foregroundImage: './assets/adaptive-icon.png',\n      backgroundColor: '#FFFFFF',\n    },\n  },\n  plugins: [['app-icon-badge', appIconBadgeConfig]],\n});\n```\n\nOptions:\n\n- `enabled` - enable/disable the plugin based on the environment (usually disabled for production builds)\n- `badges` - an array of badges, you can think of it as an array of layers that will be added to the icon. Each badge has :\n  - `text` - the text that will be displayed on the badge.\n  - `type` - the type of the badge, either `banner` or `ribbon` (default is `banner`).\n  - `position` - the position of the badge, based on the `type` property, it can be `top` or `bottom` for `banner` and `left` or `right` for `ribbon` (default is `top` for `banner` and `right` for `ribbon`).\n  - `color` - the color of the text only `black` and `white` color are supported (default is `white`).\n  - `background` - the background color of the badge, only hex format is supported (default is `#000000`).\n\n\u003e Note: please refer to [our starter](https://github.com/obytes/react-native-template-obytes/blob/master/app.config.ts) for a complete working example.\n\nThis plugin, when enabled, will use the `icon` and `android.adaptiveIcon.foregroundImage` properties in `app.json` to generate icons with badges, which will be saved in the `.expo` directory. The plugin will then update your Expo config to use these new icons instead of the original ones. If you are familiar with Expo plugins, you can take a look at the [source code](https://github.com/obytes/app-icon-badge/blob/master/app.plugin.ts).\n\n### As a library\n\nWe also wanted to make it possible to use the library in any React Native project, so we added the ability to use it as a library, but it's up to you to make it work with the build process you are using.\n\n```javascript\nimport { addBadge } from 'app-icon-badge';\nimport path from 'path';\n\nconst icon = path.resolve(__dirname, './assets/icon.png');\n\naddBadge({\n  icon,\n  dstPath: './assets/icon.environment.png', // optional, if not provided the icon will be generated in the same directory as the original icon under  the name 'icon.result.png'\n  badges: [\n    {\n      text: 'staging',\n      type: 'banner',\n      color: 'white', // by default it will be white and the only color supported for now is white and black\n      background: '#FF0000', // by default it will be black and we are only supporting hex format for colors\n    },\n    {\n      text: 'V1.0.1',\n      type: 'ribbon',\n    },\n  ],\n});\n```\n\n## API\n\n- `icon` - the path to the original icon you want to add the badge to.\n- `dstPath` - the path to the generated icon with the badge. If not provided, the icon will be generated in the same directory as the original icon under the name `icon.result.png`.\n- `badges` - an array of badges, you can think of it as an array of layers that will be added to the icon. Each badge has :\n  - `text` - the text that will be displayed on the badge.\n  - `type` - the type of the badge, either `banner` or `ribbon` (default is `banner`).\n  - `position` - the position of the badge, based on the `type` property, it can be `top` or `bottom` for `banner` and `left` or `right` for `ribbon` (default is `top` for `banner` and `right` for `ribbon`).\n  - `color` - the color of the text only `black` and `white` color are supported (default is `white`).\n  - `background` - the background color of the badge, only hex format is supported (default is `#000000`).\n\n## You can also use it as a CLI tool by running: `npx app-icon-badge ......`\n\n```\nUsage: app-icon-badge [options] [command]\n\ncommand line for app-icon-badge\n\nOptions:\n  -V, --version                   output the version number\n  -h, --help                      display help for command\n\nCommands:\n  add-badge [options] \u003ciconPath\u003e  add badge to icon using add-badge by default\n  use-config \u003cconfigPath\u003e         use json file as a config\n  help [command]                  display help for command\n```\n\n- **add-badge command**\n\n```\nUsage: app-icon-badge add-badge [options] \u003ciconPath\u003e\n\nadd badge to the icon runs by default you don't need to specify this command\n\nArguments:\n  iconPath                       required argument, icon path\n\nOptions:\n  -t, --type \u003ctype\u003e              required option (choices: \"banner\", \"ribbon\")\n  -x, --text \u003ctext\u003e              required option you need to provide text value\n  -p, --position \u003cposition\u003e      badge position banner:top,bottom and  ribbon:left,right (choices: \"top\", \"left\", \"right\", \"bottom\")\n  -b, --background \u003cbackground\u003e  badge background color\n  -c, --color \u003ccolor\u003e            badge color (choices: \"white\", \"black\", default: \"white\")\n```\n\n#### example\n\n```\nnpx app-icon-badge ./example/icon.png --type=banner --text=hello --position=top --background=#45f4ee --color=black\n```\n\n## 🚧 RoadMap\n\nThe library is still in its early stages. We have a lot of ideas to improve it and make it more useful. Here are some of the things we have already had the chance to implement, as well as our plans for additions in the future:\n\n- [x] Generate icons with environment \u0026 version badges for ios\n- [x] Expo plugin\n- [x] publish the library to npm\n- [x] Add support for Android Adaptive Icons\n- [ ] Add Tests\n- [x] Add support for custom badge colors\n- [ ] Add the ability to run as a CLI tool (WIP)\n\nFeel free to suggest any other features or contribute to the project yourself by helping us implement upcoming features.\n\n## 👀 More about the library\n\nThe library uses [Jimp](https://www.npmjs.com/package/jimp), an image-processing library for Node with zero native dependencies, to generate app icons with environment or version badges.\n\nThis Library was built to work with expo projects, but it can also be used in any React Native project and as a standalone library to generate icons with badges.\n\n\u003e Worth mentioning that this library was built to be added to the build process of our react native starter kit [Obytes Starter](https://starter.obytes.com/). The starter kit is based on the best practices and tools that we have found to be most effective in our own projects and it comes with this library pre-installed and configured. Make sure to give it a try if you are looking for a React Native starter kit.\n\n## 🔥 How to contribute?\n\nWe appreciate your desire to support our effort. We highly value your participation and look forward to receiving your contributions.\n\nIf you decided that you would like to contribute, you can follow these steps:\n\n1. Fork the repository.\n2. Create your feature branch (git checkout -b my-new-feature).\n3. Install dependencies, we use pnpm, please make sure to [install](https://pnpm.io/installation) it, if you don't have it already.\n\n```bash\ncd app-icon-badge\npnpm install\n```\n\n4. Run the example provided in the `example` directory. You should see a new icon with the badge generated in the same directory as the original icon under the name `icon.development.png`.\n\n```bash\npnpm start\n```\n\nFor a better experience, we are using `nodemon` to watch for changes and re-run the example while developing. Make sure to open the resulting image with Visual Studio Code and split the screen to see the changes live.\n\n5. Commit \u0026 push your changes then open a new Pull Request.\n\nFeel free to open an issue if you have a suggestion, question, or feedback.\n\nIf our project has helped you in any way, please consider giving it a star ⭐️.\n\n## 📝 License\n\nThis project is MIT licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobytes%2Fapp-icon-badge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobytes%2Fapp-icon-badge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobytes%2Fapp-icon-badge/lists"}