npm package: @pyyupsk/pixelarticons
Description: Modern CLI tool to generate React components from the original Pixelarticons library by Gerrit Halfmann. Built with TypeScript and comprehensive testing.
Author: pyyupsk
Latest version: 1.0.5

# @pyyupsk/pixelarticons

![Pixelarticons](https://raw.githubusercontent.com/halfmage/pixelarticons/refs/heads/master/cover.jpg)

> 🎨 CLI tool to generate React components from the beautiful Pixelarticons library

[![npm version](https://img.shields.io/npm/v/@pyyupsk/pixelarticons.svg)](https://www.npmjs.com/package/@pyyupsk/pixelarticons)
[![npm downloads](https://img.shields.io/npm/dm/@pyyupsk/pixelarticons.svg)](https://www.npmjs.com/package/@pyyupsk/pixelarticons)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@pyyupsk/pixelarticons)](https://bundlephobia.com/package/@pyyupsk/pixelarticons)
[![codecov](https://codecov.io/gh/pyyupsk/pixelarticons/graph/badge.svg?token=sVmAOBCYWP)](https://codecov.io/gh/pyyupsk/pixelarticons)
[![CI](https://github.com/pyyupsk/pixelarticons/actions/workflows/test.yml/badge.svg)](https://github.com/pyyupsk/pixelarticons/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/node/v/@pyyupsk/pixelarticons)](https://nodejs.org)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

A modern CLI tool that generates React components from the original [**Pixelarticons**](https://pixelarticons.com) by [Gerrit Halfmann](https://github.com/halfmage). This tool provides an easy way to integrate the 486 handmade pixel art icons into your React projects with full TypeScript support and tree-shaking capabilities.

> **Note:** This is a standalone CLI tool that uses the original Pixelarticons SVG assets. All icon designs are © Gerrit Halfmann and licensed under MIT. For the original icon library, visit [pixelarticons.com](https://pixelarticons.com).

## Features

✨ **Generate React components** from 486 handmade pixel art icons
🎯 **On-demand generation** - only create the icons you need
📦 **Tree-shakeable** - optimal bundle sizes
🔧 **TypeScript & JavaScript** support
⚙️ **Configurable** via `.pixelarticonsrc.json` or environment variables
🛡️ **Safe overwrites** - prompts before replacing existing components
🔗 **Path alias support** - automatically resolves `@`, `~`, `#` from tsconfig
🚀 **Fast** - built with Bun
📚 **Comprehensive** - detailed CLI guide included

## Installation

```bash
npm install @pyyupsk/pixelarticons
# or
yarn add @pyyupsk/pixelarticons
# or
bun add @pyyupsk/pixelarticons
```

## Quick Start

### 1. Initialize Configuration

```bash
npx @pyyupsk/pixelarticons init
```

This creates a `.pixelarticonsrc.json` file in your project root with default settings.

### 2. List Available Icons

```bash
# List all 486 icons
npx @pyyupsk/pixelarticons list

# Filter by name
npx @pyyupsk/pixelarticons list --filter arrow
```

### 3. Generate Components

```bash
# Generate specific icons
npx @pyyupsk/pixelarticons add archive calendar camera

# Generate all icons
npx @pyyupsk/pixelarticons add --all
```

### 4. Use in Your Code

**TypeScript:**

```tsx
import { Archive, Calendar } from "@/components/icons";

function App() {
  return (
    <div>
      <Archive size={24} />
      <Calendar size={48} className="text-blue-500" />
    </div>
  );
}
```

**JavaScript:**

```jsx
import { Archive, Calendar } from "@/components/icons";

function App() {
  return (
    <div>
      <Archive size={24} />
      <Calendar size={48} className="icon" />
    </div>
  );
}
```

## CLI Commands

### `init` - Initialize Configuration

```bash
npx @pyyupsk/pixelarticons init [options]

Options:
  -o, --output <path>    Output directory (default: "@/components/icons")
  --typescript           Use TypeScript (default: true)
  --no-typescript        Use JavaScript
  -f, --force            Overwrite existing config
```

### `list` - List Available Icons

```bash
npx @pyyupsk/pixelarticons list [options]

Options:
  -f, --filter <pattern>  Filter icons by name pattern
```

### `add` - Generate Components

```bash
npx @pyyupsk/pixelarticons add [icons...] [options]

Options:
  -a, --all              Generate all 486 icons
  -o, --output <path>    Override output directory
  --typescript           Generate TypeScript components
  --no-typescript        Generate JavaScript components
  -c, --config <path>    Custom config file path
  -f, --force            Force overwrite existing components without prompting
  -v, --verbose          Enable verbose logging
```

#### Overwrite Behavior

When regenerating existing components, the CLI will prompt you:

```bash
npx @pyyupsk/pixelarticons add home

⚠ 1 component(s) already exist:
  - home
? Overwrite existing components? (y/N)
```

- **Choose No (default)**: Skip existing components, only generate new ones
- **Choose Yes**: Overwrite all existing components
- **Use `--force`**: Skip prompt and overwrite directly

```bash
# Force overwrite without prompt (useful for CI/CD)
npx @pyyupsk/pixelarticons add home --force
```

## Configuration

Create `.pixelarticonsrc.json` in your project root:

```json
{
  "output": "@/components/icons",
  "typescript": true,
  "extension": "tsx",
  "indexFile": true
}
```

### Configuration Options

| Option       | Type    | Default                | Description                                                       |
| ------------ | ------- | ---------------------- | ----------------------------------------------------------------- |
| `output`     | string  | `"@/components/icons"` | Output directory for generated components (supports path aliases) |
| `typescript` | boolean | `true`                 | Generate TypeScript (`.tsx`) or JavaScript (`.jsx`)               |
| `extension`  | string  | `"tsx"`                | File extension (`"tsx"` or `"jsx"`)                               |
| `indexFile`  | boolean | `true`                 | Generate barrel export file (`index.ts`/`index.js`)               |

#### Path Alias Support

The CLI automatically resolves path aliases from your `tsconfig.json` or `jsconfig.json`:

```json
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "~/*": ["./*"]
    }
  }
}
```

With this configuration:

- `@/components/icons` → resolves to `./src/components/icons`
- `~/lib/icons` → resolves to `./lib/icons`

Supported aliases: `@`, `~`, `#`, and any custom aliases you define.

### Environment Variables

Override configuration using environment variables:

```bash
PIXELARTICONS_OUTPUT=./icons npx @pyyupsk/pixelarticons add archive
PIXELARTICONS_TYPESCRIPT=false npx @pyyupsk/pixelarticons add calendar
```

Available variables:

- `PIXELARTICONS_OUTPUT`
- `PIXELARTICONS_TYPESCRIPT`
- `PIXELARTICONS_EXTENSION`
- `PIXELARTICONS_INDEX_FILE`

## Component API

All generated components accept standard SVG props plus a `size` prop:

```tsx
interface IconProps extends SVGProps<SVGSVGElement> {
  size?: number | string; // Width and height (default: 24)
}
```

### Examples

```tsx
// Basic usage
<Archive />

// Custom size
<Archive size={48} />
<Archive size="3rem" />

// With styling
<Archive className="text-blue-500 hover:text-blue-700" />
<Archive style={{ color: 'red', cursor: 'pointer' }} />

// With event handlers
<Archive onClick={() => console.log('clicked')} />

// All combined
<Archive
  size={32}
  className="icon"
  style={{ marginRight: '8px' }}
  onClick={handleClick}
  aria-label="Archive icon"
/>
```

### Documentation

For developers and AI assistants working with this codebase, see [`llms.txt`](./llms.txt) for comprehensive technical documentation including:

- Internal architecture and pipeline details
- Configuration system and path alias resolution
- Component generation templates and philosophy
- Performance benchmarks and testing strategy
- Security considerations and design decisions

## Development

This repository uses the original [Pixelarticons](https://github.com/halfmage/pixelarticons) SVG assets as a git submodule.

```bash
# Clone with submodules
git clone --recursive https://github.com/pyyupsk/pixelarticons.git

# Or initialize submodules after cloning
git submodule update --init --recursive

# Build the CLI
bun install
bun run build

# Test locally
bun run dev init
bun run dev list
bun run dev add archive
```

## Credits & Attribution

This project would not be possible without the amazing work of:

### Original Icon Library

**[Pixelarticons](https://pixelarticons.com)** by **[Gerrit Halfmann](https://github.com/halfmage)** ([@halfmage](https://github.com/halfmage))

- 486 carefully handmade pixel art icons
- Based on 24×24 grid with currentColor fills
- Licensed under MIT License
- Copyright © 2019 Gerrit Halfmann

### CLI Tool

**[@pyyupsk/pixelarticons](https://github.com/pyyupsk/pixelarticons)** by **[@pyyupsk](https://github.com/pyyupsk)**

- React component generator
- TypeScript/JavaScript support
- Modern CLI with comprehensive testing

## License

This CLI tool is licensed under the [MIT License](https://github.com/pyyupsk/pixelarticons/blob/main/LICENSE)]. The original Pixelarticons SVG assets are also licensed under the MIT License by Gerrit Halfmann.

### Original Pixelarticons License

```text
MIT License

Copyright (c) 2019 Gerrit Halfmann

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
```

For the complete license text, see [halfmage/pixelarticons/LICENSE](https://raw.githubusercontent.com/halfmage/pixelarticons/refs/heads/master/LICENSE).

## Links

- 🌐 [Original Pixelarticons Website](https://pixelarticons.com)
- 📦 [npm Package](https://www.npmjs.com/package/@pyyupsk/pixelarticons)
- 🐛 [Issues](https://github.com/pyyupsk/pixelarticons/issues)
- 🎨 [Figma File](https://www.figma.com/community/file/952542622393317653/Pixelarticons)