capacitor-assets turns one logo into every icon and splash screen your app needs

One logo in, a complete set of platform assets out

The problem is unglamorous and eats an afternoon every time it is done by hand. A Capacitor app needs an icon at many pixel densities for Android, a set of AppIcon sizes for iOS, and a matching set of launch images or splash screens, plus the web manifest icons for a progressive web app. That is dozens of files derived from one design, and every platform has its own naming convention and size ladder. The tool's job is to crop and resize JPEG and PNG source images to generate icons and splash screens for iOS, Android and Progressive Web Apps. The easy mode is the recommended one, and it generates all the icon and splash assets from a single logo file along with an optional dark mode logo, and background colors. The documentation is direct about the trade, calling it the easiest way to generate all your assets while noting it trades customizability for convenience. That is the right framing for a build step that should be boring.

Easy Mode takes one logo and two colors

The source layout for easy mode is deliberately minimal. You create a single logo.png or icon.png with an optional logo-dark.png in the assets folder, and the tool also supports using SVG files as source images, substituting the .svg extension as needed.

assets/
├── logo.png
└── logo-dark.png

You then run the generate command with the background colors that will be used to build the background layers for icons and splash screens.

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

The flag list is long, and the reason is that the tool composes a logo onto a background layer rather than simply scaling a bitmap. The icon background color is used when generating icon layers for light mode with a default of #ffffff, and iconBackgroundColorDark is the same for dark mode where supported with a default of #111111. The splash background flags do the same job for splash screens. The separate dark variants are why the optional dark mode logo exists, since a system in dark mode would otherwise show a light splash.

Full Control mode asks for the layers separately

The other mode is called Custom Mode in the documentation, and it exists for when the composited look is not what you want. You provide custom icons and splash screen source images as separate files.

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

The size requirements are explicit. The icon-only and the icon foreground and background sources must each be at least 1024 by 1024 pixels, and the splash sources, including the dark variant, must be at least 2732 by 2732 pixels. That split of foreground and background is the interesting part, because it is the same layered approach the platform expects for adaptive icons, where the system may crop the foreground differently depending on the device shape. The custom mode is what a designer produces when they want to control that. With all the default options you run the generate command with no flags, and the tool applies the defaults for everything.

Platform selection is exclusive, and detection fills in the rest

The command line interface accepts a platform for the first argument, currently ios, android or pwa, and if you specify one then resources are generated only for that platform. The documentation spells out the consequence of the platform flags, and it is the kind of detail that quietly wastes an afternoon. Using a platform flag makes the platform list exclusive, so passing --ios does not mean also do Android, it means only iOS. Otherwise, the tool will use all detected Capacitor platforms, which is the normal case where a project has both an ios and an android directory. Two further flags let you point the tool at the projects themselves: --iosProject takes the path to the iOS project with a default of ios/App, and --androidProject takes the path to the Android project with a default of android. The asset source path has its own flag, --assetPath, and by default the tool will check the assets and resources directories, in that order. You can also set the width of the logo on splash screens with --logoSplashTargetWidth, or scale it as a percentage with --logoSplashScale, which defaults to 0.2.

The PWA manifest is created or updated, and the file name matters

The web app side is more than icons, and the tool writes the manifest for you. It will create and/or update the web app manifest used in your project, and it supports both the older manifest.json file and the newer manifest.webmanifest files, preferring manifest.webmanifest when no existing manifest is found. The search order for an existing manifest is public, then src, then www, and the flag --pwaManifestPath lets you specify the exact path to your web app manifest. The preference rule is the part to note, because a project that has both a legacy manifest.json in public and a newer manifest.webmanifest elsewhere will end up with the two files disagreeing about icons, since the tool prefers the webmanifest and writes there. The full flag list is available on the command line through the help flag.

npx @capacitor/assets generate --help

The install itself is a single dev dependency.

npm install --save-dev @capacitor/assets

The package is a Node CLI with sharp doing the image work

The implementation details in the package metadata explain the design constraints. The package is @capacitor/assets at version 3.0.5, with a bin entry named capacitor-assets pointing at the bin/capacitor-assets script, and the main entry at dist/index.js built from TypeScript. The image work is done by sharp at 0.32.6, which is the native image processing library and the reason the tool can crop and resize at a practical speed. The rest of the dependencies are ordinary Node plumbing, fs-extra for file operations, node-fetch for remote input, node-html-parser for reading the web manifest, commander and yargs for the command line, and debug for logging. The Ionic array and file system utilities, @ionic/utils-array and @ionic/utils-fs, are shared packages with the rest of the Ionic tooling. The engines field requires node 10.3.0 or above, and the build is a plain tsc compile with jest for tests.

Cordova support was removed, so a Cordova project has to move first

The one thing in the readme that is a migration rather than a feature is worth isolating, because it determines whether the tool is usable for you at all. Previous versions of this tool supported Cordova, but Cordova support has been removed as of 1.x, and the project strongly recommends that teams migrate to Capacitor. The current version is 3.0.5, so the tool has been Capacitor-only for a long time now, and the removal is not something you will find in a changelog entry for a recent release. For a team still on Cordova, the choice is between migrating the app to Capacitor and continuing to generate assets by hand. The repository layout is small and conventional for a published CLI package, with bin/ and src/ at the top, a test directory with jest, an eslint config, a changesets directory for versioning, and husky for git hooks.

Where capacitor-assets is the wrong choice

The first wrong case is a Cordova project, for the reason above. The second is a design team that produces bespoke artwork per platform, because the tool's output is derived, and a logo with a background color behind it is not the same as an illustration drawn for the iOS home screen. Easy mode exists for the common case and the custom mode exists for people who want to control the layers, but neither mode is a design tool. The third wrong case is a project where assets are not checked in and are regenerated on every CI run, since the documentation does not mention a mode that verifies existing assets against the sources, so the tool would happily rewrite them and you would lose the ability to hand-tune a generated file. The fourth is a monorepo with several apps, because the tool expects an assets or resources folder in the root of the project and takes one project path per platform, so a workspace with five apps means five invocations with different asset paths, which the documentation does not cover. The fifth is a project that does not use Capacitor at all, where the iOS and Android halves of the tool have nothing to hook into.

Editorial conclusion

Any team shipping a Capacitor app that has a logo and wants the full set of density-specific icons and splash screens without hand-cropping dozens of files is the audience for @capacitor/assets, and the Easy Mode path from a single logo to a complete set is the reason it exists. It is the wrong tool for a Cordova project, because support for Cordova was removed as of 1.x and the project strongly recommends migrating to Capacitor, and it is the wrong tool for a design team that needs per-platform bespoke artwork, since Easy Mode explicitly trades customizability for convenience. Check three things before you run it: that your source images meet the documented minimum sizes, since icon sources must be at least 1024 by 1024 pixels and splash sources at least 2732 by 2732 pixels, that the tool will find the assets folder, since it expects an assets or resources directory in the project root and checks assets first then resources, and that you commit the generated output rather than regenerating it in CI, because the documentation does not describe a check mode. The licence is MIT, the package version is 3.0.5 from 2024-03-29, and the last push was on 2026-10-22.

Frequently asked questions

Official sources

1. ionic-team/capacitor-assets on GitHub
2. Issues
3. License: MIT
4. README
5. Releases