Guide

# Migration

From hand-rolled icon helpers to Glyphs components — mostly autocorrected.

## What the cop rewrites

```ruby
# before                              # after
_lucide(:house, class: "size-4")      LucideIcon(:house, class: "size-4")
_hero(:check)                         HeroIcon(:check)
_heroicon(:check)                     HeroIcon(:check)
icon("check", library: "lucide")      LucideIcon("check")
icon("check")                         HeroIcon("check") # DefaultLibraryComponent
```

## The steps

1. Add `gem "glyphs"`; replace `include YourIconHelper` with `include Glyphs` in your component base class(es).
2. Add the RuboCop plugin and cop config (see [RuboCop cops](https://glyphs.zoolutions.llc/docs/rubocop-cops)).
3. **Delete your icon helper first** — otherwise the cop rewrites the helper's own internal `icon(...)` delegation.
4. Run the autocorrect:

```shell
bundle exec rubocop -A --only Glyphs/LegacyIconHelper,Glyphs/PreferLibraryComponent
```

1. Move your old missing-icon logging into `Glyphs.configure` (see [Missing icons](https://glyphs.zoolutions.llc/docs/missing-icons)).

Custom helper names map via cop config — `Mappings` *replaces* the defaults when set:

```yaml
Glyphs/LegacyIconHelper:
  Mappings:
    _custom: CustomIcon
  DefaultLibraryComponent: HeroIcon
```

## Audit forced variants first

If your helpers hardcoded variants (`icon(name, variant: "light", ...)` inside the helper body), confirm your rails_icons config reproduces them as *default variants* before autocorrecting — the components pass `variant: nil` and let the `icons` gem resolve the default. A drifted default silently changes which SVG renders. `Glyphs/IconResolution` validates against the default-variant directory, so a wrong default usually surfaces as a wall of "not found" offenses.