npm package: @nikothetsy/ng-starter-favicon
Description: Replace default Angular favicon with distinctive, pre-designed favicons - perfect for distinguishing multiple dev projects
Author: Niko Tsybulevsky
Latest version: 1.0.1

# @nikotsy/ng-starter-favicon

> Replace the default Angular favicon with distinctive, pre-designed favicons from our curated library.

[![npm version](https://img.shields.io/npm/v/@nikotsy/ng-starter-favicon.svg)](https://www.npmjs.com/package/@nikotsy/ng-starter-favicon)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 📑 Table of Contents

- [The Problem](#-the-problem)
- [The Solution](#-the-solution)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Usage](#-usage)
  - [Single Project](#single-project)
  - [Angular Workspace](#angular-workspace)
  - [Advanced Workflows](#advanced-workflows)
- [Available Favicons](#-available-favicons)
- [CLI Reference](#-cli-reference)
- [What It Does](#-what-it-does)
- [File Structure](#-file-structure)
- [Examples](#-examples)
- [Troubleshooting](#-troubleshooting)
- [FAQ](#-faq)
- [Contributing](#-contributing)
- [License](#-license)

---

## 🎯 The Problem

**Scenario:** You're a developer running 10+ Angular projects locally during development.

**Pain Point:** Every single tab shows the same default Angular "A" favicon. Which tab is which? Is that tab your admin panel or your blog? Your store or your docs site?

**Time Wasted:** Constantly clicking through tabs to find the right project. Frustrating. Inefficient.

**This tool solves that in 3 seconds.**

---

## ✨ The Solution

`ng-starter-favicon` instantly replaces your Angular project's default favicon with a distinctive, professionally-designed icon from our curated library.

**Benefits:**
- 🎨 **9 unique, hand-crafted favicons** (Angular-themed mascots and anglerfish variations)
- ⚡ **3-second setup** - one command and you're done
- 🔧 **Workspace-aware** - supports Angular monorepos with multiple projects
- 🎲 **Random mode** - assign different favicons to each project automatically
- 💾 **Safe** - automatically backs up your existing favicons
- 🌐 **Complete** - includes all modern formats (ICO, SVG, PNG, PWA manifests)

---

## 📦 Installation

**No installation required!** Use with `npx`:

```bash
npx @nikotsy/ng-starter-favicon
```

Or install globally (optional):

```bash
npm install -g @nikotsy/ng-starter-favicon
```

---

## 🚀 Quick Start

### For a single Angular project:

```bash
cd my-angular-app
npx @nikotsy/ng-starter-favicon
```

That's it! A random favicon is now applied.

### For an Angular workspace:

```bash
cd my-angular-workspace
npx @nikotsy/ng-starter-favicon --all-random
```

Each project in your workspace now has a unique favicon!

---

## 📘 Usage

### Single Project

When you run the command in a standard Angular project (created with `ng new`), a random favicon is automatically applied:

```bash
cd my-app
npx @nikotsy/ng-starter-favicon
```

**Output:**
```
🎨 ng-starter-favicon
Make your Angular project less boring ✨

✓ Detected Angular project/workspace
  Found 1 project(s)

→ my-app
  🎲 Random: anglerfish-front
  ✓ Favicon replaced successfully

✅ Successfully updated 1 project(s)
```

**Choose a specific favicon:**

```bash
npx @nikotsy/ng-starter-favicon --id mascot-left
```

**See all available favicons:**

```bash
npx @nikotsy/ng-starter-favicon --list
```

---

### Angular Workspace

For Angular workspaces with multiple projects (like Nx monorepos or multi-project Angular workspaces):

#### List all projects in your workspace

```bash
npx @nikotsy/ng-starter-favicon --list-projects
```

**Output:**
```
Projects in workspace (7):

  • root (projects/root)
  • blog (projects/blog)
  • store (projects/store)
  • admin (projects/admin)
  • agents (projects/agents)
  • ux-tools (projects/ux-tools)
  • ux-tips (projects/ux-tips)
```

#### Apply to a specific project

```bash
npx @nikotsy/ng-starter-favicon --project blog --id angular-n
```

#### Apply same favicon to ALL projects

```bash
npx @nikotsy/ng-starter-favicon --all --id anglerfish-front
```

All 7 projects now have the same favicon.

#### Apply DIFFERENT random favicons to each project

```bash
npx @nikotsy/ng-starter-favicon --all-random
```

**Output:**
```
🎲 Applying random favicon to each of 7 projects

→ root
  🎲 Random: anglerfish-front
  ✓ Favicon replaced successfully

→ blog
  🎲 Random: mascot-front
  ✓ Favicon replaced successfully

→ store
  🎲 Random: anglerfish-right
  ✓ Favicon replaced successfully

...
```

Each project gets a unique favicon - perfect for distinguishing tabs during development!

---

### Advanced Workflows

#### Skip backups (not recommended)

By default, the CLI backs up your existing `index.html` and favicon files. To skip backups:

```bash
npx @nikotsy/ng-starter-favicon --no-backup
```

**Warning:** Only use this if you're certain you don't need to restore the originals.

#### Combine options

```bash
# Apply specific favicon to specific project, no backup
npx @nikotsy/ng-starter-favicon --project admin --id mascot-front --no-backup
```

---

## 🎨 Available Favicons

Currently, **9 unique favicons** are included:

| ID | Description |
|----|-------------|
| `anglerfish-front` | Angular mascot anglerfish facing forward |
| `anglerfish-left` | Angular mascot anglerfish facing left |
| `anglerfish-right` | Angular mascot anglerfish facing right |
| `anglerfish-variation-front` | Variation of anglerfish facing forward |
| `anglerfish-variation-left` | Variation of anglerfish facing left |
| `anglerfish-variation-right` | Variation of anglerfish facing right |
| `angular-n` | Angular "N" logo favicon |
| `mascot-front` | Angular mascot facing forward |
| `mascot-left` | Angular mascot facing left |

**View them online:** [Coming soon - Landing page at tools.holdtightandpretenditsaplan.dev]

**List in terminal:**
```bash
npx @nikotsy/ng-starter-favicon --list
```

---

## 📖 CLI Reference

### Commands

```bash
npx @nikotsy/ng-starter-favicon [options]
```

### Options

| Option | Alias | Argument | Description |
|--------|-------|----------|-------------|
| `--id` | `-i` | `<favicon-id>` | Use a specific favicon by ID (see `--list`) |
| `--list` | `-l` | - | List all available favicon IDs |
| `--project` | `-p` | `<project-name>` | Target a specific project in workspace |
| `--all` | `-a` | - | Apply same favicon to all projects in workspace |
| `--all-random` | - | - | Apply different random favicon to each project |
| `--list-projects` | - | - | List all projects in the workspace |
| `--no-backup` | - | - | Skip creating backups (not recommended) |
| `--version` | `-v` | - | Show version number |
| `--help` | `-h` | - | Show help |

### Exit Codes

- `0` - Success
- `1` - Error (not an Angular project, invalid favicon ID, missing index.html, etc.)

---

## ⚙️ What It Does

When you run the CLI, here's what happens:

### 1. **Detection**
- Checks if the current directory contains `angular.json`
- Reads workspace configuration
- Identifies all application projects (ignores library projects)
- Determines project structure (`public/` vs `src/`)

### 2. **Backup** (unless `--no-backup` is used)
- Creates timestamped backup of existing `index.html`
  - Example: `index.html.backup-2025-10-25T08-28-45-123Z`
- Creates timestamped backup of existing favicon directory (if it exists)
  - Example: `favicon.backup-2025-10-25T08-28-45-123Z/`

### 3. **File Operations**
- Copies 7 favicon files from the package to your project:
  - `favicon.ico` (15KB, multi-resolution ICO)
  - `favicon.svg` (Vector, modern browsers)
  - `favicon-96x96.png` (High-DPI raster)
  - `apple-touch-icon.png` (180×180, iOS/Safari)
  - `web-app-manifest-192x192.png` (PWA icon)
  - `web-app-manifest-512x512.png` (PWA icon)
  - `site.webmanifest` (PWA manifest file)

### 4. **HTML Updates**
- Opens `src/index.html` (or `public/index.html`)
- Removes all existing favicon-related `<link>` and `<meta>` tags
- Injects new, properly-formatted tags in the `<head>` section:

```html
<link rel="icon" type="image/png" href="/favicon/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon/favicon.svg" />
<link rel="shortcut icon" href="/favicon/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/favicon/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-title" content="MyApp" />
<link rel="manifest" href="/favicon/site.webmanifest" />
```

### 5. **Verification**
- Reports success or failure for each project
- Displays summary (e.g., "✅ Successfully updated 7 project(s)")

---

## 📂 File Structure

### Where favicons are placed

The CLI automatically detects your project structure:

#### Option A: `public/favicon/` (Angular 17+)
```
my-app/
├── public/
│   └── favicon/
│       ├── favicon.ico
│       ├── favicon.svg
│       ├── favicon-96x96.png
│       ├── apple-touch-icon.png
│       ├── web-app-manifest-192x192.png
│       ├── web-app-manifest-512x512.png
│       └── site.webmanifest
└── src/
    └── index.html  ← Updated with <link> tags
```

**HTML paths:** `/favicon/favicon.ico`

#### Option B: `src/favicon/` (Angular <17)
```
my-app/
└── src/
    ├── favicon/
    │   ├── favicon.ico
    │   ├── favicon.svg
    │   └── ...
    └── index.html  ← Updated with <link> tags
```

**HTML paths:** `/favicon/favicon.ico`

#### Option C: `public/` (root-level)
```
my-app/
├── public/
│   ├── favicon.ico
│   ├── favicon.svg
│   └── ...
└── src/
    └── index.html  ← Updated with <link> tags
```

**HTML paths:** `/favicon.ico`

The CLI automatically determines the correct paths based on your structure.

---

## 💡 Examples

### Example 1: Distinguish 10 local dev projects

**Problem:** You're running 10 Angular apps locally. All tabs look the same.

**Solution:**
```bash
cd ~/my-angular-workspace
npx @nikotsy/ng-starter-favicon --all-random
```

**Result:** Each project gets a unique, colorful favicon. Now you can instantly spot which tab is which!

---

### Example 2: Brand consistency across workspace

**Problem:** Your company workspace has 5 Angular projects, all need the company logo.

**Solution:**
```bash
npx @nikotsy/ng-starter-favicon --all --id angular-n
```

**Result:** All 5 projects now have the same favicon during development.

---

### Example 3: Single project, specific favicon

**Problem:** You want your admin panel to have a specific icon.

**Solution:**
```bash
cd projects/admin
npx @nikotsy/ng-starter-favicon --id mascot-front
```

**Result:** Admin project now has the mascot favicon.

---

### Example 4: Preview favicons before choosing

**Problem:** You want to see all available favicons.

**Solution:**
```bash
npx @nikotsy/ng-starter-favicon --list
```

**Result:**
```
Available favicons:

  • anglerfish-front
  • anglerfish-left
  • anglerfish-right
  • anglerfish-variation-front
  • anglerfish-variation-left
  • anglerfish-variation-right
  • angular-n
  • mascot-front
  • mascot-left
```

Then visit the landing page (coming soon) to see visual previews.

---

## 🛠️ Troubleshooting

### "Not an Angular project"

**Error message:**
```
✗ Not an Angular project
  Run this command in an Angular project directory
```

**Cause:** The CLI couldn't find `angular.json` in the current directory.

**Solution:**
- Navigate to your Angular project root: `cd path/to/my-angular-app`
- Verify `angular.json` exists: `ls angular.json`

---

### "Multiple projects detected. Please specify..."

**Error message:**
```
⚠ Multiple projects detected. Please specify:
  --project <name>    Apply to specific project
  --all               Apply same favicon to all
  --all-random        Apply random favicon to each
  --list-projects     Show available projects
```

**Cause:** You're in an Angular workspace with multiple projects, but didn't specify which to update.

**Solution:**
- List projects: `npx @nikotsy/ng-starter-favicon --list-projects`
- Choose one of:
  - `--project <name>`
  - `--all`
  - `--all-random`

---

### "Invalid favicon ID: xyz"

**Error message:**
```
✗ Invalid favicon ID: xyz
  Run with --list to see available favicons
```

**Cause:** The favicon ID you specified doesn't exist.

**Solution:**
- List available favicons: `npx @nikotsy/ng-starter-favicon --list`
- Use a valid ID from the list

---

### "Could not find index.html"

**Error message:**
```
✗ Could not find index.html
```

**Cause:** The CLI searched common locations (`src/index.html`, `public/index.html`, `index.html`) but couldn't find your HTML file.

**Solution:**
- Verify your project structure is standard Angular
- Check if `index.html` exists
- Report an issue if your structure is valid but not detected

---

### Favicons not showing in browser

**Symptom:** CLI succeeds, but browser still shows old favicon.

**Solution:**
1. **Hard refresh:** `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
2. **Clear browser cache:** Settings → Clear browsing data → Cached images
3. **Check dev server:** Restart `ng serve` to pick up new files
4. **Verify paths:** Open `src/index.html` and confirm `<link>` tags point to `/favicon/...`

---

## ❓ FAQ

### Does this work with Nx workspaces?

**Yes!** As long as your Nx workspace has an `angular.json` file, it will work. The CLI detects all application projects and ignores libraries.

### Can I use my own custom favicons?

**Not yet.** Currently, you can only use the 9 pre-designed favicons included in the package. Custom favicon support is planned for a future release.

### Will this work in production?

**Yes, but...** this tool is designed for **development environments**. For production, you should create professional, brand-specific favicons using tools like [Favicon.io](https://favicon.io) or hire a designer.

That said, the favicons this tool installs are production-ready formats and will work perfectly fine in production if you choose.

### Does it modify my `angular.json`?

**No.** The CLI only modifies:
- `src/index.html` (or `public/index.html`)
- Files in the favicon directory

Your Angular configuration remains untouched.

### What if I want to restore the original favicon?

Your originals are backed up automatically! Look for:
- `index.html.backup-TIMESTAMP`
- `favicon.backup-TIMESTAMP/`

To restore:
```bash
mv index.html.backup-TIMESTAMP index.html
rm -rf public/favicon
mv favicon.backup-TIMESTAMP public/favicon
```

### Can I contribute more favicons?

**Absolutely!** See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

---

## 🤝 Contributing

Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
- How to add new favicons
- Development setup
- Code style guidelines
- Testing procedures

---

## 📄 License

MIT © [Niko Tsybulevsky](https://github.com/nikotsy)

---

## 🙏 Acknowledgments

- Angular mascot designs inspired by the official [Angular brand guidelines](https://angular.dev/press-kit)
- Built with [Commander.js](https://github.com/tj/commander.js/) and [Chalk](https://github.com/chalk/chalk)

---

## 📧 Support

- 🐛 **Issues:** [GitHub Issues](https://github.com/nikotsy/ng-starter-favicon/issues)
- 💬 **Discussions:** [GitHub Discussions](https://github.com/nikotsy/ng-starter-favicon/discussions)
- 🌐 **Website:** [tools.holdtightandpretenditsaplan.dev](https://tools.holdtightandpretenditsaplan.dev)

---

**Made with ❤️ for the Angular community**