image-asset-manager/README.md

A comprehensive image asset management tool for frontend projects

# 🖼️ Image Asset Manager

A comprehensive image asset management tool for frontend projects that helps you organize, optimize, and manage your image assets with ease.

## ✨ Features

- **🔍 Smart Asset Discovery**: Automatically scan and catalog all image assets in your project
- **📊 Usage Analysis**: Track which images are used and identify unused assets
- **🔄 Duplicate Detection**: Find and manage duplicate images across your project
- **⚡ Real-time Monitoring**: Watch for file changes and update asset information automatically
- **🌐 Web Interface**: Beautiful web UI for browsing and managing your assets
- **📝 Code Generation**: Generate framework-specific code for your images (React, Vue, Angular, etc.)
- **🎯 Smart Optimization**: Optimize images for better performance
- **📱 Multiple Formats**: Support for PNG, JPG, SVG, WebP, and GIF formats

## 🚀 Quick Start

### Installation

```bash
# Install globally
npm install -g image-asset-manager

# Or use with npx (no installation required)
npx image-asset-manager
```

### Basic Usage

```bash
# Start the asset manager in current directory
image-asset-manager

# Specify a project directory
image-asset-manager /path/to/your/project

# Start with custom port
image-asset-manager --port 4000

# Enable automatic optimization
image-asset-manager --optimize
```

## 📖 Commands

### Main Command

```bash
image-asset-manager [project-path] [options]
```

**Options:**

- `-p, --port <port>`: Port for the web server (default: 3000)
- `-c, --config <config>`: Path to configuration file
- `-e, --exclude <patterns...>`: Patterns to exclude (default: node_modules, .git, dist, build)
- `-i, --include <patterns...>`: Patterns to include (default: \*_/_.{svg,png,jpg,jpeg,gif,webp})
- `--no-watch`: Disable file watching
- `--optimize`: Enable automatic optimization

### Scan Only

```bash
image-asset-manager scan [project-path] [options]
```

Scan project for image assets without starting the web server.

### Web Interface Only

```bash
image-asset-manager serve [project-path] [options]
```

Start only the web interface server.

### Optimize Images

```bash
image-asset-manager optimize [project-path] [options]
```

Optimize image assets in the project.

**Options:**

- `-o, --output <dir>`: Output directory for optimized images

### Generate Code

```bash
image-asset-manager generate [project-path] [options]
```

Generate type definitions and import files.

**Options:**

- `-f, --framework <framework>`: Target framework (react, vue, angular, svelte)

## 🌐 Web Interface

The web interface provides:

- **📋 Asset Gallery**: Browse all your images with thumbnails
- **🔍 Advanced Search**: Filter by type, category, usage status, and more
- **📊 Statistics Dashboard**: Overview of your asset usage and optimization opportunities
- **🔄 Duplicate Manager**: Identify and resolve duplicate images
- **📝 Code Generator**: Generate framework-specific code snippets
- **⚙️ Settings**: Configure optimization and scanning options

Access the web interface at `http://localhost:3000` (or your specified port).

## ⚙️ Configuration

Create a `.imagemanager.json` file in your project root:

```json
{
  "include": ["src/**/*.{png,jpg,svg,webp}"],
  "exclude": ["node_modules/**", "dist/**"],
  "optimization": {
    "enabled": true,
    "quality": 85,
    "progressive": true
  },
  "frameworks": ["react", "vue"],
  "categories": {
    "icons": "src/assets/icons/**",
    "images": "src/assets/images/**",
    "backgrounds": "src/assets/backgrounds/**"
  }
}
```

## 🔧 API Reference

The tool provides a REST API for integration:

### Endpoints

- `GET /api/health` - Health check
- `GET /api/images` - List all images (supports pagination and filtering)
- `GET /api/images/:id` - Get specific image details
- `GET /api/stats` - Project statistics
- `GET /api/duplicates` - Duplicate groups
- `GET /api/search` - Search images with advanced filters
- `POST /api/generate-code` - Generate framework-specific code
- `GET /api/usage/:id` - Get usage analysis for specific image

### WebSocket Events

Real-time updates via WebSocket connection:

- `data-updated` - Asset data has been updated
- `file-changed` - File system changes detected
- `optimization-complete` - Image optimization finished

## 🎯 Framework Integration

### React

```javascript
// Generated import
import heroImage from "./assets/hero.png";

// Usage
<img src={heroImage} alt="Hero" />;

// SVG as component
import { ReactComponent as LogoIcon } from "./assets/logo.svg";
<LogoIcon />;
```

### Vue

```javascript
// Generated import
import heroImage from './assets/hero.png';

// Usage in template
<img :src="heroImage" alt="Hero" />
```

### Angular

```typescript
// In component
export class MyComponent {
  heroImage = 'assets/hero.png';
}

// In template
<img [src]="heroImage" alt="Hero" />
```

## 🛠️ Development

### Prerequisites

- Node.js 16+
- npm or yarn

### Setup

```bash
# Clone the repository
git clone https://github.com/your-username/image-asset-manager.git
cd image-asset-manager

# Install dependencies
npm install

# Install web dependencies
cd web && npm install && cd ..

# Build the project
npm run build

# Run tests
npm test

# Start development
npm run dev
```

### Scripts

- `npm run build` - Build the entire project
- `npm run dev` - Start development mode with watch
- `npm run test` - Run tests
- `npm run lint` - Lint code
- `npm run version:patch` - Bump patch version
- `npm run version:minor` - Bump minor version
- `npm run version:major` - Bump major version
- `npm run release` - Release to npm
- `npm run release:dry` - Dry run release

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Reporting Issues

Please use the [GitHub Issues](https://github.com/your-username/image-asset-manager/issues) page to report bugs or request features.

### Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite
6. Submit a pull request

## 📚 Examples

### Basic Project Setup

```bash
# Navigate to your project
cd my-react-app

# Start image asset manager
npx image-asset-manager

# Open web interface
open http://localhost:3000
```

### CI/CD Integration

```yaml
# .github/workflows/assets.yml
name: Asset Management
on: [push, pull_request]

jobs:
  check-assets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: "16"
      - run: npx image-asset-manager scan --no-watch
      - run: npx image-asset-manager optimize --output dist/assets
```

## 🔗 Related Tools

- [Sharp](https://sharp.pixelplumbing.com/) - Image processing
- [SVGO](https://github.com/svg/svgo) - SVG optimization
- [Chokidar](https://github.com/paulmillr/chokidar) - File watching

## 📈 Roadmap

- [ ] Plugin system for custom processors
- [ ] Integration with popular bundlers (Webpack, Vite, Rollup)
- [ ] Advanced image analysis (color palette, dimensions, etc.)
- [ ] Batch operations and automation
- [ ] Cloud storage integration
- [ ] Performance monitoring and analytics

---

Made with ❤️ by the Image Asset Manager team