Guide

# Missing icons

Raise loudly in development, degrade gracefully in production.

## The policy

Configured once, in an initializer.

```ruby
Glyphs.configure do |config|
  # Re-raise Icons::IconNotFound? Defaults to true in local Rails
  # environments (and outside Rails), false otherwise.
  config.raise_on_missing = Rails.env.local?

  # Rendered instead of the missing icon (per library).
  # A library without an entry re-raises.
  config.fallback_icons = {
    lucide: "circle-question-mark",
    phosphor: "question",
    heroicons: "question-mark-circle"
  }
end
```

With `raise_on_missing` true a typo fails fast in development and test. With it false (production), the library's fallback icon renders instead so the page never 500s over a missing glyph. If the fallback itself is missing, the original error re-raises — no silent loops.

## The instrumentation hook

`on_missing_icon` is an optional handler, called before the fallback renders (never when raising). Wire it to your logger or error tracker:

```ruby
Glyphs.configure do |config|
  config.on_missing_icon = lambda do |error, name:, library:, variant:|
    Rails.logger.error(
      "Icon missing: #{library}/#{variant}/#{name} (#{error.message})"
    )
  end
end
```

## Interaction with the SVG cache

Fallback renders are cached under the *original* icon name, so `on_missing_icon` fires **once per process per missing icon**, not on every render — your logs stay readable while the fallback keeps rendering. Set `config.cache_svgs = false` to trade that for a notification per render.