All Projects → dwmkerr → App Icon

dwmkerr / App Icon

Licence: mit
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.

Programming Languages

java
68154 projects - #9 most used programming language

Projects that are alternatives of or similar to App Icon

Cordova Plugin Media Capture
Apache Cordova Plugin media-capture
Stars: ✭ 271 (-46.23%)
Mutual labels:  mobile, cordova
Cordova Android
Apache Cordova Android
Stars: ✭ 3,285 (+551.79%)
Mutual labels:  mobile, cordova
Cupertino Pane
🎉📱Multi-functional panes and boards for next generation progressive applications
Stars: ✭ 267 (-47.02%)
Mutual labels:  mobile, cordova
perfect-ubuntu
js dev setup, just for fun
Stars: ✭ 14 (-97.22%)
Mutual labels:  icons, apps
Gradle Play Publisher
GPP is Android's unofficial release automation Gradle Plugin. It can do anything from building, uploading, and then promoting your App Bundle or APK to publishing app listings and other metadata.
Stars: ✭ 3,690 (+632.14%)
Mutual labels:  apps, mobile
Ionic-ElastiChat-with-Images
Ionic Magic Chat with Angular Elastic, Autolinker.js and more!
Stars: ✭ 66 (-86.9%)
Mutual labels:  cordova, apps
Cordova
Apache Cordova
Stars: ✭ 291 (-42.26%)
Mutual labels:  mobile, cordova
Cordova Plugins
Apache Cordova
Stars: ✭ 242 (-51.98%)
Mutual labels:  mobile, cordova
Cordova Plugin Media
Apache Cordova Plugin media
Stars: ✭ 338 (-32.94%)
Mutual labels:  mobile, cordova
Cordova Plugin Device
Apache Cordova Plugin device
Stars: ✭ 327 (-35.12%)
Mutual labels:  mobile, cordova
ionic4-angular7-example
Ionic 4, Angular 7 and Cordova Tutorial: Build CRUD Mobile Apps
Stars: ✭ 57 (-88.69%)
Mutual labels:  cordova, apps
Cordova Plugin Network Information
Apache Cordova Plugin network-information
Stars: ✭ 429 (-14.88%)
Mutual labels:  mobile, cordova
Syncing Thesis
Syncing strategies for mobile apps.
Stars: ✭ 97 (-80.75%)
Mutual labels:  apps, mobile
Cordova Plugin Dialogs
Apache Cordova Plugin dialogs
Stars: ✭ 267 (-47.02%)
Mutual labels:  mobile, cordova
Fastlane
🚀 The easiest way to automate building and releasing your iOS and Android apps
Stars: ✭ 33,382 (+6523.41%)
Mutual labels:  apps, mobile
Framework7
Full featured HTML framework for building iOS & Android apps
Stars: ✭ 16,560 (+3185.71%)
Mutual labels:  mobile, cordova
Cordova Lib
Apache Cordova Tooling Library
Stars: ✭ 208 (-58.73%)
Mutual labels:  mobile, cordova
Cordova Osx
Apache Cordova mac
Stars: ✭ 232 (-53.97%)
Mutual labels:  mobile, cordova
Cordova Docs
Apache Cordova Documentation
Stars: ✭ 315 (-37.5%)
Mutual labels:  mobile, cordova
Cordova Plugman
Apache Cordova Plugman
Stars: ✭ 379 (-24.8%)
Mutual labels:  mobile, cordova

app-icon

npm version CircleCI AppVeyor Build Status codecov dependencies Status devDependencies Status GuardRails badge Greenkeeper badge Conventional Commits

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. Node 10 and onwards supported.

Banner

Introduction

This 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.

Create a single large icon.png at least 192 pixels square, or run app-icon init to create this icon, then run:

# If you are using npm 5.2 onwards...
npx app-icon generate

# ...for older versions of npm
npm install -g app-icon
app-icon generate

You can also use the module directly in node:

/**
 * appIcon = {
 *   labelImage(inputFilePath, outputFilePath, topText, bottomText),
 *   generate({ sourceIcon, platforms, search }),
 *   templates: {
 *     'AndroidManifest.icons': {...json file...},
 *     'AppIcon.iconset': {...json file...},
 *   },
 * }
 */
import appIcon from 'app-icon';

Promise.resolve()
  .then(() => appIcon.labelImage('./inputfile.png', './out.png', 'UAT', '0.12.3'))
  .then(() => appIcon.labelImage('./inputfile.png', './out.png', 'UAT')) // Bottom text optional
  .then(() => appIcon.labelImage('./inputfile.png', './out.png', null, '0.12.3')) // Top text optional
  .then(() => appIcon.generate()) // will use all default values
  .then(() => appIcon.generate({
    sourceIcon: './icon.png', // Path of the icon to use
    platforms: 'android,ios', // The platforms to generate icons for (i.e. 'android')
    search: './',
  }));

Installation

Install with:

npm install -g app-icon

You will need imagemagick installed:

brew install imagemagick          # OSX
sudo apt-get install imagemagick  # Debian/Ubuntu/etc
sudo yum install imagemagick      # CentOS/etc

Usage

The app-icon tool can be used to create a simple template icon, generate icons of all sizes from a template icon, or label icons.

Initialising

If 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:

app-icon init                    # generates an icon named icon.png

You can also add a simple label to the icon.

app-icon init --caption "App"    # creates an icon with the text 'App'

To create template Adaptive Icons for Android include the --adaptive-icons flag.

Generating Icons

Add 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:

app-icon generate

If an iOS project is present, then the icon will be copied at all required sizes to:

./ios/<ProjectName>/Images.xcassets/AppIcon.appiconset

If an Android project is present, then the icon will be copied at all required sizes to:

./android/app/src/main/res

You can limit the platforms which icons are generated for with the --platforms flag, specifying:

app-icon generate --platforms=ios
app-icon generate --platforms=android,ios

By default the tool will generate icons for both platforms.

You can search in specific directories for icons, if the presence of other projects is interfering, just use the --search or -s parameter:

app-icon generate -s ./ios -s ./android

You 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.

Labelling Icons

Add labels to an icon with the command below:

app-icon label -i icon.png -o output.png --top UAT --bottom 0.12.3

This would produce output like the below image:

Labelled Icon Image

This 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.

To label adaptive icons, simply run the label command against the foreground adaptive icon image.

Adaptive Icons

Support for Adaptive Icons for Android is being introduced. This will happen in stages and should be considered an 'alpha' feature until otherwise noted.

The current goals are:

  1. Adaptive Icons are 'opt in' for now, they won't be generated by default
  2. Creating or generating adaptive icons is done via the --adaptive-icons flag

None 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!

There is an excellent guide on developing Adaptive Icons here.

To test how adaptive icons will look when animated, swiped, etc, the Adaptive Icons website by Marius Claret is very useful!

Note 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.

Developer Guide

The only dependencies are Node 10 (or above) and Yarn.

Useful commands for development are:

Command Usage
npm test Runs the unit tests.
npm run test:debug Runs the tests in a debugger. Combine with .only and debugger for ease of debugging.
npm run cov Runs the tests, writing coverage reports to ./artifacts/coverage.

Currently the linting style is based on airbnb. Run npm run lint to lint the code.

Initial Setup

Install the dependencies (I recommend Node Version Manager):

nvm install 8
nvm use 8
git clone [email protected]:dwmkerr/app-icon.git
cd app-icon
npm install && npm test

Running Tests

Run the tests with:

npm test

Tests are executed with Mocha and coverage is handled by Istanbul. Coverage reports are written to an ./artifacts folder.

Note that best practices are to pass Mocha a quoted string with a glob pattern for cross-platform execution of tests (see Mocha Docs). 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.

Commit Messages

Conventional Commits 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.

Creating a Release

To create a release.

  • Merge your work to master.
  • Use npm run release.
  • Push and deploy git push --tags && git push && npm publish

Note that semantic-version is used, meaning a changelog is automatically kept up to date, and versioning is handled semantically based on the commit message.

Builds

Builds are run on CircleCI. You can run the CircleCI build locally with the following command:

make circleci

The 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.

Debugging

The 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:

DEBUG=app-icon app-icon generate --platforms android

The Sample Projects

This 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.

React Native

To run:

cd ./test/ReactNativeIconTest/
npm install
react-native run-ios
# OR react-native run-android

Cordova

To run:

cd ./test/CordovaApp/
npm install
cordova run ios
# OR cordova run android

Native

To run the native apps, open the ./test/NativeApp directory, then open the iOS/Android projects in XCode/AndroidStudio as needed.

Compatibility

app-icon dependds on ImageMagick. 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.

The table below shows the current confirmed compatibility:

Platform app-icon ImageMagick Status
OSX 0.6.x 6, 7
Ubuntu 14 0.6.x 6

Troubleshooting

Images labelled with app-icon label have the text slightly vertically offset

This seems to be an issue with Imagemagick 6 - try upgrading to 7.

License

MIT

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].