{"id":13989020,"url":"https://github.com/dwmkerr/app-icon","last_synced_at":"2025-05-16T01:06:08.311Z","repository":{"id":46577338,"uuid":"66092356","full_name":"dwmkerr/app-icon","owner":"dwmkerr","description":"Icon management for Mobile Apps. Create icons, generate all required sizes, label and annotate. Supports Native, Cordova, React Native, Xamarin and more. Inspired by cordova-icon.","archived":false,"fork":false,"pushed_at":"2021-10-05T02:41:15.000Z","size":40467,"stargazers_count":567,"open_issues_count":39,"forks_count":58,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-09T12:41:58.997Z","etag":null,"topics":["android","apps","cordova","icons","ios","mobile","react-native"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dwmkerr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"dwmkerr"}},"created_at":"2016-08-19T15:27:57.000Z","updated_at":"2025-04-20T07:38:01.000Z","dependencies_parsed_at":"2022-08-29T21:41:35.094Z","dependency_job_id":null,"html_url":"https://github.com/dwmkerr/app-icon","commit_stats":null,"previous_names":["dwmkerr/react-native-icon"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwmkerr%2Fapp-icon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwmkerr%2Fapp-icon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwmkerr%2Fapp-icon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwmkerr%2Fapp-icon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dwmkerr","download_url":"https://codeload.github.com/dwmkerr/app-icon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"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","apps","cordova","icons","ios","mobile","react-native"],"created_at":"2024-08-09T13:01:29.122Z","updated_at":"2025-05-16T01:06:03.302Z","avatar_url":"https://github.com/dwmkerr.png","language":"Java","funding_links":["https://github.com/sponsors/dwmkerr"],"categories":["Java"],"sub_categories":[],"readme":"# app-icon\n\n[![npm version](https://badge.fury.io/js/app-icon.svg)](https://badge.fury.io/js/app-icon) [![CircleCI](https://circleci.com/gh/dwmkerr/app-icon.svg?style=shield)](https://circleci.com/gh/dwmkerr/app-icon) [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/3e334rknhjbpx555?svg=true)](https://ci.appveyor.com/project/dwmkerr/app-icon) [![codecov](https://codecov.io/gh/dwmkerr/app-icon/branch/master/graph/badge.svg)](https://codecov.io/gh/dwmkerr/app-icon) [![dependencies Status](https://david-dm.org/dwmkerr/app-icon/status.svg)](https://david-dm.org/dwmkerr/app-icon) [![devDependencies Status](https://david-dm.org/dwmkerr/app-icon/dev-status.svg)](https://david-dm.org/dwmkerr/app-icon?type=dev) [![GuardRails badge](https://badges.guardrails.io/dwmkerr/app-icon.svg?token=569f2cc38a148f785f3a38ef0bcf5f5964995d7ca625abfad9956b14bd06ad96\u0026provider=github)](https://dashboard.guardrails.io/default/gh/dwmkerr/app-icon) [![Greenkeeper badge](https://badges.greenkeeper.io/dwmkerr/app-icon.svg)](https://greenkeeper.io/) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\nIcon management for Mobile Apps. Create icons, generate all required sizes, label and annotate. Supports Native, Cordova, React Native, Xamarin and more. Inspired by [cordova-icon](https://github.com/AlexDisler/cordova-icon). Node 10 and onwards supported.\n\n\u003cimg src=\"./assets/banner/banner.png\" width=\"614\" alt=\"Banner\"\u003e\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Introduction](#introduction)\n* [Installation](#installation)\n* [Usage](#usage)\n    * [Initialising](#initialising)\n    * [Generating Icons](#generating-icons)\n    * [Labelling Icons](#labelling-icons)\n    * [Adaptive Icons](#adaptive-icons)\n* [Developer Guide](#developer-guide)\n    * [Initial Setup](#initial-setup)\n    * [Running Tests](#running-tests)\n    * [Commit Messages](#commit-messages)\n    * [Creating a Release](#creating-a-release)\n    * [Builds](#builds)\n    * [Debugging](#debugging)\n* [The Sample Projects](#the-sample-projects)\n    * [React Native](#react-native)\n    * [Cordova](#cordova)\n    * [Native](#native)\n* [Compatibility](#compatibility)\n* [Troubleshooting](#troubleshooting)\n* [License](#license)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Introduction\n\nThis simple tool allows you to create a single icon in your app project, then create icons of all required sizes from it. It currently works for iOS and Android. You can also add labels to your app icons.\n\nCreate a single large `icon.png` at least 192 pixels square, or run `app-icon init` to create this icon, then run:\n\n```bash\n# If you are using npm 5.2 onwards...\nnpx app-icon generate\n\n# ...for older versions of npm\nnpm install -g app-icon\napp-icon generate\n```\n\nYou can also use the module directly in node:\n\n```js\n/**\n * appIcon = {\n *   labelImage(inputFilePath, outputFilePath, topText, bottomText),\n *   generate({ sourceIcon, platforms, search }),\n *   templates: {\n *     'AndroidManifest.icons': {...json file...},\n *     'AppIcon.iconset': {...json file...},\n *   },\n * }\n */\nimport appIcon from 'app-icon';\n\nPromise.resolve()\n  .then(() =\u003e appIcon.labelImage('./inputfile.png', './out.png', 'UAT', '0.12.3'))\n  .then(() =\u003e appIcon.labelImage('./inputfile.png', './out.png', 'UAT')) // Bottom text optional\n  .then(() =\u003e appIcon.labelImage('./inputfile.png', './out.png', null, '0.12.3')) // Top text optional\n  .then(() =\u003e appIcon.generate()) // will use all default values\n  .then(() =\u003e appIcon.generate({\n    sourceIcon: './icon.png', // Path of the icon to use\n    platforms: 'android,ios', // The platforms to generate icons for (i.e. 'android')\n    searchRoot: './',\n  }));\n```\n\n## Installation\n\nInstall with:\n\n```bash\nnpm install -g app-icon\n```\n\nYou will need [imagemagick](http://www.imagemagick.org/) installed:\n\n```bash\nbrew install imagemagick          # OSX\nsudo apt-get install imagemagick  # Debian/Ubuntu/etc\nsudo yum install imagemagick      # CentOS/etc\n```\n\n## Usage\n\nThe `app-icon` tool can be used to create a simple template icon, generate icons of all sizes from a template icon, or label icons.\n\n### Initialising\n\nIf you do not already have a single icon to use as the main icon for your project, you can create one with the `init` command:\n\n```bash\napp-icon init                    # generates an icon named icon.png\n```\n\nYou can also add a simple label to the icon.\n\n```bash\napp-icon init --caption \"App\"    # creates an icon with the text 'App'\n```\n\nTo create template [Adaptive Icons for Android](https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive) include the `--adaptive-icons` flag.\n\n### Generating Icons\n\nAdd an icon (ideally at least 192x192 pixels) named `icon.png` to your project root (or run `app-icon init`). To automatically generate icons of all sizes for all app projects in the same folder, run:\n\n```bash\napp-icon generate\n```\n\nIf an iOS project is present, then the icon will be copied at all required sizes to:\n\n```\n./ios/\u003cProjectName\u003e/Images.xcassets/AppIcon.appiconset\n```\n\nIf an Android project is present, then the icon will be copied at all required sizes to:\n\n```\n./android/app/src/main/res\n```\n\nYou can limit the platforms which icons are generated for with the `--platforms` flag, specifying:\n\n```bash\napp-icon generate --platforms=ios\napp-icon generate --platforms=android,ios\n```\n\nBy default the tool will generate icons for both platforms.\n\nYou can search in specific directories for icons, if the presence of other projects is interfering, just use the `--search` or `-s` parameter:\n\n```bash\napp-icon generate -s ./ios -s ./android\n```\n\nYou can specify the path to the source icon, as well as the folder to search for app projects, just run `app-icon generate -h` to see the options.\n\n### Labelling Icons\n\nAdd labels to an icon with the command below:\n\n```bash\napp-icon label -i icon.png -o output.png --top UAT --bottom 0.12.3\n```\n\nThis would produce output like the below image:\n\n![Labelled Icon Image](./assets/label.png)\n\nThis is a useful trick when you are creating things like internal QA versions of your app, where you might want to show a version number or other label in the icon itself.\n\nTo label adaptive icons, simply run the `label` command against the _foreground_ adaptive icon image.\n\n### Adaptive Icons\n\nSupport for [Adaptive Icons for Android](https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive) is being introduced. This will happen in stages and should be considered an 'alpha' feature until otherwise noted.\n\nThe current goals are:\n\n1. Adaptive Icons are 'opt in' for now, they won't be generated by default\n2. Creating or generating adaptive icons is done via the `--adaptive-icons` flag\n\nNone of the current commands support the `--adaptive-icons` flag. The `init` command will be the first to bring support, then `generate`. If the feature is working well for users then I will document in detail its usage, until then it is an 'experimental' feature!\n\nThere is an excellent guide on developing Adaptive Icons [here](https://medium.com/google-design/designing-adaptive-icons-515af294c783).\n\nTo test how adaptive icons will look when animated, swiped, etc, the [Adaptive Icons](https://adapticon.tooo.io/) website by [Marius Claret](https://twitter.com/mariusclaret) is very useful!\n\nNote that Adaptive Icons of *all* supported sizes are generated. However, we also generate the `res/mipmap-anydpi-v26/` adaptive icon. This is a large size icon which Android from v26 onwards will automatically rescale as needed to all other sizes. This technically makes the density specific icons redundant. The reason we generate both is to ensure that after `generate` is run, *all* icons in the project will be consistent.\n\n## Developer Guide\n\nThe only dependencies are Node 10 (or above) and Yarn.\n\nUseful commands for development are:\n\n| Command              | Usage                                                                                    |\n|----------------------|------------------------------------------------------------------------------------------|\n| `npm test`           | Runs the unit tests.                                                                     |\n| `npm run test:debug` | Runs the tests in a debugger. Combine with `.only` and `debugger` for ease of debugging. |\n| `npm run cov`        | Runs the tests, writing coverage reports to `./artifacts/coverage`.                      |\n\nCurrently the linting style is based on [airbnb](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb). Run `npm run lint` to lint the code.\n\n### Initial Setup\n\nInstall the dependencies (I recommend [Node Version Manager](https://github.com/creationix/nvm)):\n\n```bash\nnvm install 8\nnvm use 8\ngit clone git@github.com:dwmkerr/app-icon.git\ncd app-icon\nnpm install \u0026\u0026 npm test\n```\n\n### Running Tests\n\nRun the tests with:\n\n```bash\nnpm test\n```\n\nTests are executed with [Mocha](https://mochajs.org/) and coverage is handled by [Istanbul](https://github.com/gotwarlost/istanbul). Coverage reports are written to an `./artifacts` folder.\n\nNote that best practices are to pass Mocha a quoted string with a glob pattern for cross-platform execution of tests (see [Mocha Docs](https://mochajs.org/#the-test-directory)). However for some reason on AppVeyor this doesn't seem to work. Leaving the pattern unquoted works for `cmd` as well as the shell in builds for now. So please be careful if changing the quotes and test on both platforms.\n\n### Commit Messages\n\n[Conventional Commits](https://www.conventionalcommits.org) should be used. This allows the CHANGELOG to be kept up to date automatically, and ensures that semantic versioning can be expected from the library.\n\n### Creating a Release\n\nTo create a release.\n\n- Merge your work to master.\n- Use `npm run release`.\n- Push and deploy `git push --tags \u0026\u0026 git push \u0026\u0026 npm publish`\n\nNote that `semantic-version` is used, meaning a changelog is automatically kept up to date, and versioning is handled semantically based on the commit message.\n\n### Builds\n\nBuilds are run on CircleCI. You can run the CircleCI build locally with the following command:\n\n```\nmake circleci\n```\n\nThe builds use custom docker images which contain the appropriate Node.js runtime, as well as the ImageMagick binaries. These custom images are stored in the `.circleci/images` folder. You can use the `.circleci/images/makefile` makefile to build them, but permissions to push to the `dwmkerr` Docker Hub account are required to publish these images. In general, these should not need to be modified.\n\n### Debugging\n\nThe [`debug`](https://www.npmjs.com/package/debug) package is used to support low-level debugging. If you want to see debug messages when running the tool, just set the `DEBUG` environment variable to `app-icon`:\n\n```sh\nDEBUG=app-icon app-icon generate --platforms android\n```\n\n## The Sample Projects\n\nThis project includes some sample apps in the `test` folder, which are used for the tests. You can also run these apps to see the icons produced in action.\n\n### React Native\n\nTo run:\n\n```bash\ncd ./test/ReactNativeIconTest/\nnpm install\nreact-native run-ios\n# OR react-native run-android\n```\n\n### Cordova\n\nTo run:\n\n```bash\ncd ./test/CordovaApp/\nnpm install\ncordova run ios\n# OR cordova run android\n```\n\n### Native\n\nTo run the native apps, open the `./test/NativeApp` directory, then open the iOS/Android projects in XCode/AndroidStudio as needed.\n\n## Compatibility\n\n`app-icon` dependds on [ImageMagick](https://www.imagemagick.org/). ImageMagick 6 is installed by default on many Linux distributions, as well as OSX. Some platforms are regularly tested (such as Ubuntu, via CircleCI). Other platforms *may* work but are not tested when I make a release, so your results may vary.\n\nThe table below shows the current confirmed compatibility:\n\n| Platform  | `app-icon` | ImageMagick | Status |\n|-----------|------------|-------------|--------|\n| OSX       | `0.6.x`    | 6, 7        | ✅     |\n| Ubuntu 14 | `0.6.x`    | 6           | ✅     |\n\n## Troubleshooting\n\n**Images labelled with `app-icon label` have the text slightly vertically offset**\n\nThis seems to be an issue with Imagemagick 6 - try upgrading to 7.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwmkerr%2Fapp-icon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdwmkerr%2Fapp-icon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwmkerr%2Fapp-icon/lists"}