npm package: @lucasbernardosn/img2ico
Description: Ferramenta CLI para converter imagens para o formato ICO.
Author: @LucasBernardoSN
Latest version: 1.0.0

<div align="center">
  <h1 align="center">Image To Ico Converter CLI</h1>
</div>

## Sobre o projeto

Ferramenta CLI para converter imagens de diversos formatos para o formato ICO de múltiplos tamanhos. Facilita a criação de favicons e ícones de aplicações.

O projeto foca em simplicidade de uso, validação de entrada e feedback do processo de conversão.

### Principais funcionalidades

- Conversão automática para os tamanhos suportados por arquivos ico (16, 24, 32, 48, 64, 128, 256px)
- Suporte para múltiplos formatos de entrada (JPEG, PNG, WebP, AVIF, BMP, GIF, TIFF)
- Validação de arquivos de entrada (formato, tamanho, existência)
- Interface CLI com feedback em tempo real
- Uso como biblioteca TypeScript em outros projetos
- Tratamento de erros com mensagens claras
- Redimensionamento com preservação de transparência

### Tecnologias utilizadas

[![Node.js][node-shield]](https://nodejs.org/) — Runtime JavaScript  
[![TypeScript][typescript-shield]](https://www.typescriptlang.org/) — Tipagem estática  
[![Sharp][sharp-shield]](https://sharp.pixelplumbing.com/) — Processamento de imagens  
[![to-ico][toico-shield]](https://www.npmjs.com/package/to-ico/) — Geração de arquivos ICO  
[![Yargs][yargs-shield]](https://yargs.js.org/) — Parser de argumentos CLI  
[![Biome][biome-shield]](https://biomejs.dev/) — Linting e formatação  
[![pnpm][pnpm-shield]](https://pnpm.io/) — Gerenciador de pacotes

## Como começar

### Pré-requisitos

Node.js 18.0.0+

### Instalação

Para rodar localmente:

Clonar o repositório:

```bash
git clone https://github.com/LucasBernardoSN/image-to-ico-converter-cli.git
```

Entrar no diretório:

```bash
cd image-to-ico-converter-cli
```

Instalar dependências:

```bash
pnpm install
```

Compilar o projeto:

```bash
pnpm run build
```

### Instalação global

Instalar globalmente via npm:

```bash
npm install -g @lucasbernardosn/img2ico
```

Usar o comando img2ico em qualquer lugar:

```bash
img2ico -i logo.png
```

## Como usar

### Comandos básicos

| Comando                              | Descrição                                   |
| ------------------------------------ | ------------------------------------------- |
| `pnpm start -i <entrada>`            | Converte imagem para ICO no diretório atual |
| `pnpm start -i <entrada> -o <saida>` | Converte especificando arquivo de saída     |
| `img2ico -i <entrada>`               | Comando global (após instalação global)     |
| `pnpm start --help`                  | Exibe ajuda e opções disponíveis            |

### Exemplos práticos

Converter logo.png para logo.ico:

```bash
pnpm start -i logo.png
```

Especificar arquivo de saída personalizado:

```bash
pnpm start -i foto.jpg -o favicon.ico
```

Usar com caminho absoluto:

```bash
pnpm start -i /path/to/image.png -o /path/to/output.ico
```

Comando global após instalação:

```bash
img2ico -i logo.png -o icon.ico
```

### Formatos suportados

**Entrada:** JPEG, PNG, WebP, AVIF, BMP, GIF, TIFF  
**Saída:** ICO com múltiplos tamanhos (16, 24, 32, 48, 64, 128, 256px)

## Como biblioteca

Use o conversor programaticamente em seus projetos TypeScript/JavaScript:

```typescript
import { ImageToIcoConverter, ConsoleLogger } from '@lucasbernardosn/img2ico';

const converter = new ImageToIcoConverter(new ConsoleLogger());

try {
  const result = await converter.convert({
    inputPath: 'input.png',
    outputPath: 'output.ico', // opcional
  });

  if (result.success) {
    console.log(`✅ Conversão concluída: ${result.outputPath}`);
    console.log(`📁 Tamanho: ${result.fileSizeBytes} bytes`);
    console.log(`⏱️  Tempo: ${result.processingTimeMs}ms`);
    console.log(`🎯 Tamanhos gerados: ${result.generatedSizes.join(', ')}px`);
  }
} catch (error) {
  console.error('❌ Erro na conversão:', error.message);
}
```

### Interface personalizada

```typescript
import { ImageToIcoConverter } from '@lucasbernardosn/img2ico';

// Logger customizado
class CustomLogger {
  info(message: string) {
    /* sua implementação */
  }
  success(message: string) {
    /* sua implementação */
  }
  error(message: string) {
    /* sua implementação */
  }
  warning(message: string) {
    /* sua implementação */
  }
}

const converter = new ImageToIcoConverter(new CustomLogger());
```

## Scripts disponíveis

| Script           | Comando          | Descrição                          |
| ---------------- | ---------------- | ---------------------------------- |
| Executar CLI     | `pnpm start`     | Compila e executa a ferramenta CLI |
| Compilar         | `pnpm run build` | Compila TypeScript para JavaScript |
| Verificar código | `pnpm run lint`  | Executa verificação com Biome      |

## Contato

Lucas Bernardo — [lucasbernardo.dev@gmail.com](mailto:lucasbernardo.dev@gmail.com)

## Licença

MIT © 2025 Lucas Bernardo. Veja [LICENSE](./LICENSE).

<!-- SHIELDS URL -->

[node-shield]: https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white
[typescript-shield]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white
[sharp-shield]: https://img.shields.io/badge/Sharp-99CC00?style=for-the-badge&logo=sharp&logoColor=white
[toico-shield]: https://img.shields.io/badge/to--ico-FF6B6B?style=for-the-badge&logo=npm&logoColor=white
[yargs-shield]: https://img.shields.io/badge/Yargs-FF6347?style=for-the-badge&logo=javascript&logoColor=white
[biome-shield]: https://img.shields.io/badge/Biome-60A5FA?style=for-the-badge&logo=biome&logoColor=white
[pnpm-shield]: https://img.shields.io/badge/pnpm-F69220?style=for-the-badge&logo=pnpm&logoColor=white