DEV Community

arialus
arialus

Posted on

Stop installing giant icon packages — write SVGs as source with a CLI + MCP

#javascript #opensource #webdev #mcp

The pain nobody admits in the PR

You need a house icon, an arrow, a settings gear, and the GitHub logo.

So you install Lucide. Then someone on the team already used Tabler. The marketing site copied Heroicons. Brand marks came from a random SVG dump. Six months later:

  • node_modules carries thousands of icons you never render
  • imports disagree on naming (House vs IconHome vs home)
  • agents invent Lucide paths that don’t exist
  • design asks for “the same icon but from that other set”

Lucide, Tabler, Heroicons, Feather, Remix theyre excellent art. Theyre a weak delivery model when your app only needs twelve icons from four families.

I wanted something closer to a package manager: search a huge catalog, pull only what I need, commit the SVG as source, and let Cursor / Claude use the same engine without hallucinating.

That’s Aria Icons.

What Aria Icons actually is

Not another Lucide clone. Peers worth comparing: Iconify (catalog) and better-icons. Aria’s bet is:

  1. Browser over ~340k SVGs Lucide, Tabler, Heroicons, Feather, Remix, brands via theSVG, Iconify-backed collections, and more
  2. CLI (npx aria-icons) that searches a hosted API and writes icons into your repo as source — no fat icon dependency
  3. MCP for Cursor / Claude — local stdio or remote HTTP — so agents search and fetch the same catalog

Site: https://icons.leularia.com

Repo: https://github.com/LeulAria/Aria-Icons (MIT)

npm: aria-icons

Quickstart (concrete, copy-paste) 

npx -y aria-icons@latest setup
# or: bunx aria-icons@latest setup
Enter fullscreen mode Exit fullscreen mode

Search the catalog:

npx aria-icons search house
Enter fullscreen mode Exit fullscreen mode

Print one icon (SVG or framework-oriented output depending on flags/docs):

npx aria-icons get lucide:house
Enter fullscreen mode Exit fullscreen mode

Add icons as files in the project:

npx aria-icons add lucide:house tabler:arrow-up thesvg:github
Enter fullscreen mode Exit fullscreen mode

Ids look like collection:name — e.g. lucide:house, tabler:arrow-up, thesvg:github.

When you’re already in mixed-library hell:

npx aria-icons doctor
npx aria-icons suggest src/
npx aria-icons migrate --to lucide
Enter fullscreen mode Exit fullscreen mode

The CLI stays tiny on purpose. It talks to the Aria Icons API and only downloads the icons you request. Your lockfile doesn’t inherit 340k SVGs.

Give agents a real catalog (MCP)

Coding agents are great at wiring components and terrible at remembering every icon name across every set. Aria Icons MCP exposes search/fetch over the same index the CLI uses.

Remote HTTP (hosted with the site):

{
  "mcpServers": {
    "aria-icons": {
      "url": "https://icons.leularia.com/api/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Local stdio (what aria-icons setup configures for Cursor / Claude / VS Code-style clients):

{
  "mcpServers": {
    "aria-icons": {
      "command": "npx",
      "args": ["-y", "aria-icons"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Typical loop that works well in practice:

  1. Ask the agent to search for an icon via MCP
  2. Review the pick in the browser if you care about aesthetics
  3. aria-icons add … so the SVG lands in source control

Agents get truth; humans keep commit hygiene.

How this differs from Lucide / Iconify / “just copy SVG”

Approach Strength Weakness
Single set package (Lucide, etc.) Cohesive style, great DX for one family Fat install; multi-set reality breaks the model
Iconify Huge catalog, flexible You still need a workflow for “icons as source in this repo” + agent tooling
Manual SVG paste Zero dependency Drift, duplicates, no search, agents invent junk
Aria Icons Catalog + write-as-source CLI + MCP You’re choosing a workflow, not a single aesthetic brand

Positioning in one line: icon package manager + agent surface, not an art set competing with Lucide’s drawings.

Architecture sketch (why the CLI isn’t a megapackage)

The interesting part is the shape:

  • Fat index on the server — search metadata for ~340k icons (vendored sets, Iconify collections, brand logos)
  • Thin client — npm package aria-icons is a CLI + MCP entrypoint, not the database
  • Write path — add materializes only chosen icons into your tree
  • Audit path — doctor / suggest / migrate for teams that already mixed libraries

Public REST used by the CLI (tiny payloads): search, icon by id, batch, collections, similar, equivalent/cross-set mapping. MCP rides the same catalog.

That means:

  • CI doesn’t download an icon universe
  • design-system PRs review actual SVG files
  • agents and humans share one source of truth

A realistic workflow for a design system

  1. Open icons.leularia.com and search visually when taste matters
  2. Standardize on ids (lucide:… etc.) in tickets
  3. Engineers run aria-icons add (or let MCP propose, then add)
  4. Occasionally run doctor on src/ before a release
  5. Use migrate --to <set> when consolidating

You’re not forbidden from using Lucide React components forever — you’re free to stop pretending one package covers every brand mark and every one-off.

Open source details

  • License: MIT
  • Contribute new sets via the in-app /contribute flow (and PRs)
  • Brand logos refresh from theSVG; Iconify sets can be fetched/indexed into the catalog

If you maintain icon metadata, tags, and aliases — those PRs matter as much as new drawings. Search quality is the product.

What I’m looking for feedback on

  • CLI UX: is migrate / doctor / suggest the right surface, or too much?
  • MCP tools: what should agents get next (similar icons, framework wrappers, Figma-ish naming)?
  • Messaging: does package manager for icons” land, or do people still hear another icon set”?

Try it, then decide 

npx -y aria-icons@latest setup
npx aria-icons search house
npx aria-icons add lucide:house
Enter fullscreen mode Exit fullscreen mode

If the workflow sticks after you try it, starring the repo helps other developers discover it. If it doesn’t, tell me why in the comments — that feedback is more useful than a polite star.

Top comments (1)

Collapse
 
arialus profile image
arialus •

Thanks for being among the early readers. I’d love to hear where icon workflows break down for you—mixed sets, bundle size, naming, or agent-generated guesses? If you want to kick the tires, npx -y aria-icons@latest setup is the quickest path; the source is at github.com/LeulAria/Aria-Icons. What would make this useful in your day-to-day workflow?