@capawesome/capacitor-assets

Generates the icons and splash screens of a Capacitor app for iOS, Android and Progressive Web Apps, from a single logo or from your own source images.

This is the maintained fork of @capacitor/assets by Capawesome. It is a drop-in replacement: only the package name changed. See Migrating from @capacitor/assets.

Getting started

1. Install the package:

   npm install --save-dev @capawesome/capacitor-assets
   

2. Put a logo.png of at least 1024×1024px, ideally with a transparent background, into an assets/ folder in the root of your project.

3. Generate the assets for every platform in your project:

   npx @capawesome/capacitor-assets generate
   

The icons and splash screens are written straight into your iOS, Android and web projects. Run the command again whenever the logo changes.

To set your brand colors, see Easy Mode. To use your own icons and splash screens instead of a logo, see Custom Mode.

Source files

The tool reads its source files from the assets/ folder in the root of your project, or from resources/ if that exists instead. Use --assetPath to point at another folder. There are two ways to fill it.

Easy Mode

Easy Mode generates everything from one logo. It is the recommended way: less work for you, and the result looks the same on every platform. It trades customizability for convenience.

assets/
├── logo.png
├── logo-dark.png
├── icon-monochrome.png
└── icon-maskable.png

The logo is placed on a background color for the icons and on another one for the splash screens. Pass your brand colors as options:

npx @capawesome/capacitor-assets generate --iconBackgroundColor '#eeeeee' --splashBackgroundColor '#eeeeee' --splashBackgroundColorDark '#111111'

On the splash screens, the logo is one fifth of the width by default. Change that with --logoSplashScale or --logoSplashTargetWidth, see Options.

Custom Mode

Custom Mode gives you full control: you provide the icon layers and the splash screens yourself.

assets/
├── icon-only.png
├── icon-foreground.png
├── icon-background.png
├── icon-monochrome.png
├── icon-maskable.png
├── splash.png
└── splash-dark.png

Custom files win over the logo. If the folder holds both, the custom files overwrite what the logo generated for the same output. logo.png plus splash.png, for example, gives icons from the logo and splash screens from splash.png.

Platform-specific files

Files in assets/ios/ and assets/android/ apply to one platform only and take precedence over the file in assets/ that produces the same output. The names match, with one exception: the app icon is icon-only.png in assets/, but ios/icon.png and android/icon.png in the platform folders (a root icon.png is an Easy Mode logo).

Generated assets

Without a platform option, generate runs for every platform it finds in the project. Pass --ios, --android or --pwa to pick platforms:

npx @capawesome/capacitor-assets generate --ios --android

iOS

Written to ios/App/App/Assets.xcassets/ (change the project path with --iosProject):

• AppIcon.appiconset/: the 1024×1024px app icon, plus the dark and tinted variants when ios/icon-dark and ios/icon-tinted exist. The icon is placed on --iconBackgroundColor, because iOS needs an opaque icon.
• Splash.imageset/: the 2732×2732px universal splash screens at 1x, 2x and 3x, in light and dark mode. The Contents.json files are updated and the template images are removed.

Android

Written to android/app/src/main/res/ (change the project path with --androidProject and the flavor with --androidFlavor):

• mipmap-<density>/ic_launcher_foreground.png, ic_launcher_background.png and ic_launcher_monochrome.png, with mipmap-anydpi-v26/ic_launcher.xml and ic_launcher_round.xml: the adaptive icon. The monochrome layer is only referenced when a monochrome source file exists. The layers are full bleed, with the source at --androidAdaptiveIconScale of the layer (1 for sources drawn to Android's 108dp template).
• mipmap-<density>/ic_launcher.png and ic_launcher_round.png: the legacy launcher icons for Android 7.1 and older. In Easy Mode the logo is placed on --iconBackgroundColor.
• drawable-<orientation>[-night]-<density>/splash.png: the splash screens shown by the Splash Screen plugin.
• AndroidManifest.xml: android:icon and android:roundIcon point at the generated icons.

Android 12+ launch screen

Android 12 and later draw the launch screen from the activity theme: one centered icon on a solid color, not a full-screen image. Until the theme points at an icon, the system shows the launcher icon, and splash.png only appears afterwards through the Splash Screen plugin. The tool therefore also:

• writes drawable[-night]-<density>/ic_splash.png: the middle 36% of the splash as a 288dp square. Android masks it to a 192dp circle, so keep the artwork inside the middle 24% of the splash. In Easy Mode, keep --logoSplashScale at or below 0.24, or --logoSplashTargetWidth at or below 655.
• writes the color splash_background to values[-night]/colors.xml: the color of the top-left pixel of the splash. Other colors in the file are kept.
• sets windowSplashScreenBackground and windowSplashScreenAnimatedIcon on the AppTheme.NoActionBarLaunch style in values/styles.xml, and removes its android:background item if it is @drawable/splash: below Android 12 it covers the icon with the full-screen splash. The style must extend Theme.SplashScreen, which it does since Capacitor 4. If it does not, the tool prints a warning and leaves styles.xml alone.

With the logo centered on a plain background, the launch screen then looks like the splash screen on iOS.

Notification icon

If assets/android/notification-icon.png exists, the tool writes drawable-<density>/ic_notification.png at 24, 36, 48, 72 and 96px. Android only renders the alpha channel of this icon, so use white pixels on a transparent background. Use --androidNotificationIconName to change the resource name.

Then point your notification plugin at it:

• @capacitor/push-notifications and @capacitor-firebase/messaging: add this to the <application> element of android/app/src/main/AndroidManifest.xml:

  <meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@drawable/ic_notification" />
  

• @capacitor/local-notifications: set smallIcon to ic_notification in the plugin configuration.

• @onesignal/capacitor-plugin: OneSignal reads a fixed resource name, so generate the icon under that name:

  npx @capawesome/capacitor-assets generate --androidNotificationIconName ic_stat_onesignal_default
  

  To tint the icon on Android 12 and later, add this to the <application> element (ARGB hex without #):

  <meta-data android:name="com.onesignal.NotificationAccentColor.DEFAULT" android:value="FF00FF00" />
  

PWA

The web directory is public, src or www, whichever exists first. The images are written to its assets/icons/ folder if the web directory has an assets/ folder, otherwise to its icons/ folder. The tool writes:

• icon-<size>.png with purpose: "any" and icon-maskable-<size>.png with purpose: "maskable", for the sizes 48, 72, 96, 128, 192, 256 and 512. In Easy Mode the logo is placed on --iconBackgroundColor, so the icons are opaque. A custom icon-only.png is used as is for the any icons. A custom icon-maskable.png is used as is for the maskable icons. Without it, the maskable icons inset the artwork to about three quarters of the icon on --iconBackgroundColor, so it survives the launcher masks; artwork that reaches the corners can still be clipped by round masks.
• apple-splash-<width>-<height>@<density>.png: the iOS splash screens (apple-touch-startup-image) for a built-in list of iPhone and iPad screen sizes, based on the Apple Human Interface Guidelines and updated with new releases of this tool. In Easy Mode the logo is placed on --splashBackgroundColor, or on --splashBackgroundColorDark for dark mode.
• The manifest (manifest.webmanifest, or manifest.json if that is what exists) is created or updated with the icons and, when --splashBackgroundColor is given, with background_color. Use --pwaManifestPath to point at a specific file.

Options

Logo and colors:

Colors are hex values. Quote them so your shell does not read # as a comment: '#eeeeee'.

See the full list on the command line:

npx @capawesome/capacitor-assets generate --help

Migrating from @capacitor/assets

npm uninstall @capacitor/assets
npm install --save-dev @capawesome/capacitor-assets

Replace @capacitor/assets with @capawesome/capacitor-assets in your scripts. The source files and options are the same. What changed:

• PWA icons are written as icon-<size>.png and icon-maskable-<size>.png, with separate any and maskable entries in the manifest. Earlier versions wrote PNG data to icon-<size>.webp files with a combined purpose. The old files are removed from the manifest and deleted from icons/ on the next run. Update references to them, for example apple-touch-icon links in your index.html.
• In Easy Mode, the logo is one fifth of the splash on every platform. Earlier versions scaled it by its own width on iOS and drew every Android density on its own.
• Android adaptive icon layers are full bleed, fixing a black line on the bottom and right edges at some launcher sizes. Regenerate the icons.
• --pwaNoAppleFetch has no effect. Apple removed the screen size table the tool used to fetch, so the sizes come from a built-in list.

See the changelog for everything else that was added since the fork.

Contributing

See CONTRIBUTING.md.

License

See LICENSE.