Generate automatically resized splashscreens and icons for mobile platforms, e.g. for Cordova based projects.
Installation
Inside of your project directory:
% npm install resources-generator
The script depends on imageMagick, it needs to be installed: macOS:
% brew install imagemagick
Linux / apt:
% sudo apt-get install imagemagick
Usage
Your splash template should be a 2732x2732px image, and the main content should fit a center square of 1200x1200px.
Your icon template should be a 1024x1024px image. For Android you have to take care of the rounded corners yourself, everything you don't want to see must be transparent - so your best choice is to use a png-template. Please also note chapter transparency below.
When using the default specifications or the command-line version you need to prepare your templates as following:
- Splashscreen template for Android and iOS as
./model/splash.png
- Icon template for Android as
./model/android/icon.png
- Icon template for iOS as
./model/ios/icon.png
For any individual requirements please see chapter in your own scripts.
From the command-line
The package includes a binary that can be called as resources-generator
from within your project (or from everywhere when the package was installed globally).
When called without any parameters a hint on how to use it is given:
% resources-generatorUsage: resources-generator --platform= --type= [--source="./image.png"] [--targetDir="./put/it/here/"]Please provide at least platform and type.
The binary uses the default targets for Android respectively iOS as described
in specifications, you can change the source-image
(via --source="./myimage.png"
) and the directory where the results shall
be saved (via --targetDir
).
Hint: To be able to directly use locally installed node binaries make sure
to add the following to your .bashrc
or .zshrc
:
# use locally installed node bins PATH="./node_modules/.bin:$PATH"
In your own scripts
If you want to define your own specifications the best choice is to build your own script.
A good starting point are the predefined specifications from dist/specs
.
Example:
;; //change the template for Android splashcreensandroidSplashDefaults.sourceFile = "./model/android/splash.png"; //add additional 256px Android iconandroidIconDefaults.targets.push; // create icons for our PWA, based on the android icon template; //collect all resources we want to generate; //create one after the otherresources.reduce, Promise.resolve;
You may save this script inside of your projects as scripts/generate-resources.ts
and add to your package.json
:
{
...
"scripts": {
...
"resources:generate": "cross-env TS_NODE_COMPILER_OPTIONS='{ \"module\": \"commonjs\" }' ts-node scripts/generate-resources.ts"
},
...
}
Now you are able to call npm run resources:generate
to regenerate your resources.
For a plain node example please see bin/resources-generator
.
Special cases
NinePatch images
Android supports NinePatch drawables
for its splashscreens - this project automatically generates them when your targets fileName
has the extension *.9.png
, e.g. screen-mdpi-portrait.9.png
.
The Android splashscreen defaults in dist/specs
are configured to generate NinePatch files.
Hint: To make nine-patch splashscreen work in Cordova projects you need to set
in your config.xml
!
Transparency
When nothing else is declared Alpha channel (transparency) is removed from the resulting resource images.
If you want to keep transparency you need to set this in your ResourceDefinition
by declaring keepAlpha
as true
.
The Android icon defaults in dist/specs
are configured to preserve transparency.
As NinePatch images are based on transparent areas alpha channel is preserved here in every case.
Small templates
As noted your templates should be 2732x2732px for splashscreens. This requirement is based on the required image size for iPad Pro splashscreens, see Apple Human Interface Guidelines.
If you request the script to generate a resource image that is bigger then the provided template the template is never scaled up! Instead we stretch the most outer regions until the desired size is met (this kind-of imitates what is done with NinePatch images).
Specifications
To generate resources your input needs to follow some specifications, they are described by interfaces that can be imported from the package.
To make the script usable straight away we defined some defaults for splashscreens and icons for Android and iOS.
They can be imported from dist/specs
.
We predefined the following:
Android splashscreens (uses 9-Patch!, ldpi to xxxhdpi)
;
iOS splashscreens (Storyboards)
;
Android icons (ldpi to xxxhdpi, Play Store Icon)
;
iOS icons (for all current devices, App Store Icon)
;
Add to your Cordova project
You can add the resources generated by the specifications described above to your Cordova project config.xml
in the following way:
Thanks
This script is inspired by splashicon-generator and TiCons.
It makes use of gm and imageMagick.