IcoMoon and npm: the three workflows that actually work

Option 1 — Vendor the export, let the bundler work

The most reliable path is also the least clever: keep the zip the generator app gives you in your repo, unpack it into src/assets/icomoon via a script in package.json, and import the generated stylesheet from your entry file. Because the files live inside src, Vite or webpack treats them like any other asset: the url("fonts/…") references in the CSS get resolved, hashed and cache-busted automatically.

{
  "scripts": {
    "icons:extract": "extract-zip vendor/icomoon.zip src/assets/icomoon",
    "prebuild": "npm run icons:extract",
    "build": "vite build"
  },
  "devDependencies": {
    "extract-zip": "^2.0.1"
  }
}

// src/main.js (or main.ts) — one import, the bundler does the rest
import "./assets/icomoon/style.css";

// anywhere in your markup:
// <span class="icon-home" aria-hidden="true"></span>

Commit both vendor/icomoon.zip and the selection.json inside it. The zip makes builds reproducible on a fresh clone; selection.json lets anyone on the team re-open the exact project in the app and add glyphs without starting over. If you have never generated an export, the app tutorial walks through it in about 5 minutes.

Option 2 — Skip npm entirely with jsDelivr

The free 491-icon set lives in the public IcoMoon-Free repository on GitHub, and jsDelivr can serve any file in that repo as a CDN asset — no package.json entry, no install step, no lockfile churn. For prototypes and CodePen-style demos this is the fastest route from zero to a loadable font:

/* No npm involved at all: jsDelivr mirrors the GitHub repo */
@font-face {
  font-family: "IcoMoon-Free";
  src: url("https://cdn.jsdelivr.net/gh/Keyamoon/IcoMoon-Free@master/Font/IcoMoon-Free.ttf")
    format("truetype");
}
/* Pin @master to a tag or commit hash before shipping to production */

Two caveats. First, pin the ref: @master floats, and a repo change upstream can silently alter what your page loads. Second, this route only covers the free set — custom selections and premium packs never pass through it. Version pinning, cache headers and fallback strategy get a full treatment in the CDN guide.

Option 3 — Community CLI tools that re-export for you

The manual bottleneck in option 1 is the round trip through the browser app every time a designer adds an icon. A small ecosystem of community tools — the best known is published on the npm registry as icomoon-cli — automates that trip: they drive the generator in a headless browser, upload your selection.json plus any new SVGs, trigger the font build and download the fresh zip into your project.

# Community tooling, installed as a build-time devDependency
npm install --save-dev icomoon-cli

# Flags differ between forks — read the README of the exact
# version you install before wiring it into CI.

To be clear about what you are adopting: these tools are community-maintained, not built or endorsed by Keyamoon, and they depend on the app's page structure staying stable — a UI change upstream can break them until a maintainer catches up. Check the commit history and open issues before wiring one into CI, pin the exact version, and keep option 1 as your fallback. Used with those expectations, they remove real friction on teams that touch their icon set weekly.

Pitfalls that bite in a Node pipeline

Three recurring ones. Blank squares after a build almost always mean the font URLs broke — the generated CSS references fonts/ relative to the CSS file, so moving style.css without its folder 404s every glyph. Class-name lookups mid-code are faster on the cheat sheet than in the raw CSS. And one license note: the free set is GPL / CC BY 4.0, fine to vendor and ship — but never publish files from the paid packs to a public registry; that redistribution is exactly what the license forbids.