npm package: @mirai/icons
Description: React icons wrapper
Latest version: 0.1.19

# @mirai/icons

`@mirai/icons` is a curated collection of tree-shakeable React components that wrap SVG icons from the `react-icons` project. Icons are published as individual files so modern bundlers only ship what you import, keeping bundles lean while staying fully compatible with React 19 and server-side rendering.

## Highlights
- Works with React 19 and JSX runtime; no custom Babel plugins required
- Pure SVG output with support for `size`, `color`, `title`, and native SVG props
- Individual ESM modules for every icon to keep bundlers tree-shaking friendly
- Zero runtime dependencies beyond React itself
- Lightweight tooling powered by Babel for predictable builds

## Installation

```bash
npm install @mirai/icons
# or
yarn add @mirai/icons
```

`react` and `react-dom` 19 are required by the package and will be installed automatically if you do not have them yet.

## Importing Icons

Each icon lives in its own module. Import the symbols you need directly from their folder to avoid pulling the whole catalogue:

```jsx
import { MdOutlineCheck } from '@mirai/icons/md/MdOutlineCheck';
import { RiWifiLine } from '@mirai/icons/ri/RiWifiLine';
import { TbSofa } from '@mirai/icons/tb/TbSofa';

export function AmenitiesList() {
  return (
    <ul>
      <li><MdOutlineCheck size={18} color="#27ae60" /> Free cancellation</li>
      <li><RiWifiLine size={18} /> High-speed Wi-Fi</li>
      <li><TbSofa size={18} /> Lounge area</li>
    </ul>
  );
}
```

### Component Props

All icon components expose the same API because they are generated through `IconBase`:

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `size` | `string \| number` | `'1em'` | Accepts pixel values, rem/em, `%`, etc. |
| `color` | `string` | `'currentColor'` | Sets both `fill` and `stroke` unless the SVG overrides it. |
| `className` | `string` | `undefined` | Adds CSS classes to the root `<svg>`. |
| `style` | `React.CSSProperties` | `{}` | Merged with an automatically computed `color`. |
| `title` | `string` | `undefined` | Renders a `<title>` node for accessibility. |
| `...svgProps` | `SVGProps<SVGSVGElement>` | - | Forwarded to the `<svg>` tag (e.g. `role`, `aria-*`, event handlers). |

### Building Custom Icons

If you need to wrap your own SVG path with the same look and feel you can use `IconBase` directly:

```jsx
import { IconBase } from '@mirai/icons/lib/IconBase';

export function CustomLogo(props) {
  return (
    <IconBase viewBox="0 0 32 32" {...props}>
      <circle cx="16" cy="16" r="16" />
      <path d="M10 10h12v12H10z" fill="var(--brand-color)" />
    </IconBase>
  );
}
```

`GenIcon` is also exported (`@mirai/icons/lib/GenIcon`) and can be used to create icon components from the JSON payloads produced by `react-icons` if you need to bootstrap new symbols programmatically.

## Icon Families

The repository currently ships a focused subset of families taken from `react-icons`. The table below lists the available directories, their source, and how many icons are already bundled.

| Directory | Prefix | Source Library | Icons |
| --- | --- | --- | --- |
| `md` | `Md` | Material Design Icons | 152 |
| `ri` | `Ri` | Remix Icons | 9 |
| `tb` | `Tb` | Tabler Icons | 5 |
| `lu` | `Lu` | Lucide Icons | 3 |
| `pi` | `Pi` | Phosphor Icons | 3 |
| `gi` | `Gi` | Game Icons | 2 |
| `gr` | `Gr` | Grommet Icons | 2 |
| `fa6` | `Fa` | Font Awesome 6 | 1 |
| `io` | `Io` | Ionicons | 1 |
| `lia` | `Lia` | Line Awesome | 1 |

> Tip: search the repository (e.g. `rg --files src/md`) to discover the exact component names you can import.

## Project Layout

```
src/
|-- lib/              # Shared helpers (IconBase, GenIcon)
|-- md/               # Material Design icons (largest catalogue)
|-- ri/               # Remix icons
|-- tb/               # Tabler icons
|-- lu/               # Lucide icons
|-- pi/               # Phosphor icons
|-- gi/               # Game icons
|-- gr/               # Grommet icons
|-- fa6/              # Font Awesome 6 icon(s)
|-- io/               # Ionicons
`-- lia/              # Line Awesome icons
```

The build output preserves this structure inside the published `build/` folder so consumers can rely on deep imports like `@mirai/icons/md/MdOutlineCheck` without carrying unrelated assets.

## Development Workflow

### Requirements
- Node.js >= 22.11.0
- Yarn >= 1.22

### Setup

```bash
git clone <repository-url>
cd icons
yarn install
```

### Common Scripts
- `yarn build` - Clean the previous build, install dependencies, transpile sources with Babel, and normalise extensions.
- `yarn lint` - Run ESLint (`@mirai/eslint`) with autofix and caching.
- `yarn pipeline` - Run linting followed by the production build.
- `yarn build:stats` - Inspect generated bundles with `source-map-explorer`.
- `yarn release` - Bump the patch version and publish to npm (requires proper credentials).
- `yarn setup` - Reinstall dependencies from scratch (useful when regenerating lockfiles).

For a deeper look at the build and automation scripts that support these commands, see [`agents.md`](./agents.md).

## Adding New Icons

1. Locate the desired component from `react-icons` (the `@react-icons/all-files` package on unpkg is handy https://github.com/react-icons/react-icons/releases/download/v5.5.0/react-icons-all-files-5.5.0.tgz).
2. Copy the generated `.mjs` file into the matching folder under `src/` (for example `src/md/`).
3. Ensure the file keeps the header comment (`// THIS FILE IS AUTO GENERATED`) and uses relative imports to `../lib/index.mjs` as the existing files do.
4. Update this README if the new icon belongs to a family not already listed or if you want to highlight notable additions.
5. Run `yarn pipeline` to lint and build the project; commit the new assets once everything passes.

## Releasing

Publishing is automated through the `yarn release` script which bumps the package version and pushes the build to npm. Make sure you:
- run `yarn pipeline` first
- have an updated `CHANGELOG` (if applicable)
- are logged in with `npm whoami`

## License

MIT (c) Mirai

---

Made with care by the Mirai team.