# ๐ React Native App Icon Generator
A lightweight and hassle-free CLI tool to **generate iOS and Android app icons** in your React Native project from a **single 1024x1024 PNG image** โ no config required, just run and go!
---
## โจ Features
โ
One command to generate all required icons
โ
No manual image resizing needed
โ
Automatically finds your `app_icon.png`
โ
Replaces icons in the correct native folders
โ
CLI options for background, platform, output dir
โ
Supports adaptive Android icons
โ
Works with any React Native structure
โ
Interactive mode if no arguments are provided
---
## ๐ง How to Use
### 1๏ธโฃ Option 1: Let It Find `app_icon.png` Automatically
Place a high-resolution **`1024x1024`** PNG named **`app_icon.png`** anywhere in your project.
๐ Example:
```
your-project/
โโโ src/
โ โโโ assets/
โ โโโ app_icon.png
```
Then run:
```bash
npx rn-app-icon-generator
```
---
### 2๏ธโฃ Option 2: Provide Icon Path Manually
You can specify your own icon path:
```bash
npx rn-app-icon-generator ./assets/your_icon.png \
--background "#ffffff" \
--platform all \
```
---
### 3๏ธโฃ Use Additional CLI Options
```bash
npx rn-app-icon-generator ./assets/your_icon.png \
--background "#ffffff" \
--platform all \
--output ./custom-icons \
--mask ./assets/masks/circle-mask.png (png or svg)
```
---
## โ๏ธ CLI Options
| Option | Description |
| -------------- | ------------------------------------------------------------------ |
| `--background` | Background color (hex format). Default: `#ffffff` |
| `--platform` | Platform to generate: `android`, `ios`, or `all`. Default: `all` |
| `--output` | Optional output directory (useful for preview/testing) |
| `--mask` | Optional mask file (PNG/SVG) for Android adaptive icons foreground |
> ๐ก If no arguments are provided, the tool enters interactive mode.
---
## ๐งฑ Mask Support (Adaptive Android Icons)
The `--mask` option allows shaping the foreground icon for Android adaptive icons.
โ
Supported Mask Formats:
- `.png` โ black & transparent areas (alpha mask)
- `.svg` โ vector path (e.g., circle, rounded square)
## ๐ผ๏ธ How It Works:
- The mask is applied to the foreground icon (`ic_launcher_foreground.png`)
- Using alpha masking or SVG shape with `sharp.composite(..., blend: "dest-in")`
- This creates a custom-shaped icon for modern Android launchers
## ๐ Example Usage:
```
npx rn-app-icon-generator ./assets/your_icon.png \
--background "#ffffff" \
--platform all \
--mask ./assets/masks/circle-mask.svg
```
## ๐จ PNG Mask Example
A 1024x1024 PNG with:
- **White or opaque** = visible area
- **Black or transparent** = cropped area
## ๐ Example:
```
./assets/masks/circle-mask.svg
```
## ๐งญ SVG Mask Example
Example `circle-mask.svg`:
[Download SVG](https://raw.githubusercontent.com/ara-apps-dev/rn-app-icon-generator/main/assets/circle.svg)
You can also use:
- Rounded rectangles
- Circle
- Any SVG path
---
## ๐ Output Paths
| Platform | Path Example |
| -------------------- | ------------------------------------------------------------------------------- |
| **Android** | `android/app/src/main/res/mipmap-*/ic_launcher.png` and `ic_launcher_round.png` |
| **Android Adaptive** | `mipmap-*/ic_launcher_foreground.png`, plus `ic_launcher.xml` & `colors.xml` |
| **iOS** | `ios/YourApp/Images.xcassets/AppIcon.appiconset/` with `Contents.json` |
---
## ๐ฆ Optional: Local Installation
Install as a dev dependency:
```bash
npm install rn-app-icon-generator --save-dev
```
Run with:
```bash
npx rn-app-icon-generator
```
---
## ๐ง Pro Tips
- โ
PNG **must be 1024x1024** for best results (no SVG support).
- ๐งผ Use solid backgrounds unless transparency is intentional.
- ๐ฑ Make sure iOS folder has a valid \`.xcodeproj\` file.
- ๐งช Works on both macOS, Linux, and Windows.
---
## ๐ป Example Script (CI/CD)
```bash
npx rn-app-icon-generator ./branding/your_icon.png --background "#000000" --platform all
```
Add to your `package.json` scripts:
```json
"scripts": {
"generate:icons": "rn-app-icon-generator ./branding/your_icon.png --background '#ffffff' --platform all"
}
```
---
## ๐ License
Licensed under the **MIT License**.
---
> Created by [Ara Apps Dev](https://github.com/ara-apps-dev)