wmt-polyicon

SVG to icon font generator — drop in SVGs, get a production-ready Fontello-style icon font with one command.

Converts a folder of SVGs into woff2, woff, ttf, eot, svg font files plus CSS, JS constants, and an interactive preview page.

Install

# global (recommended)
npm i -g wmt-polyicon

# or project dev dependency
npm i -D wmt-polyicon

# or one-off
npx wmt-polyicon init

Quick Start

polyicon init                    # creates .polyiconrc with defaults
# edit .polyiconrc → set "svg" to your SVG folder
polyicon generate                # builds fonts, CSS, types, and preview

That's it — 3 steps:

1. polyicon init
2. Change "svg" path in .polyiconrc
3. polyicon generate

Config (.polyiconrc)

Running polyicon init creates a fully commented config file:

{
  // Path to your SVG icons folder (change this to your SVG folder)
  "svg": "./public/assets/svg",

  // Output paths
  "outputFonts": "./public/assets/fontello/font",
  "outputStyles": "./public/assets/fontello/css/fontello.css",
  "outputTypes": "./public/assets/fontello/IconTypes.js",
  "polyiconConfig": "./public/assets/fontello/config.json",

  // Font URL prefix used inside the generated CSS (relative to CSS file)
  "importFontsPath": "../font/",
  // Font file formats to generate
  "formats": ["eot", "svg", "ttf", "woff", "woff2"],
  // Font family name used in CSS and font filenames
  "fontName": "fontello",
  // CSS class prefix (e.g. "icon" → .icon-home, "pi" → .pi-home)
  "classPrefix": "icon",
  // Append content hash to output folder for cache busting (e.g. fontello-a3f7b2c1/)
  "hashOutput": true
}

Config Reference

| Field | Default | Description | |---|---|---| | svg | ./public/assets/svg | Required. Folder containing your .svg icon files | | outputFonts | ./public/assets/fontello/font | Where font files (fontello.woff2, etc.) are written | | outputStyles | ./public/assets/fontello/css/fontello.css | CSS file output path | | outputTypes | ./public/assets/fontello/IconTypes.js | JS constants file output path | | polyiconConfig | ./public/assets/fontello/config.json | Fontello-compatible config output path | | importFontsPath | ../font/ | Font URL prefix in generated CSS — use relative path or CDN URL | | formats | ["eot","svg","ttf","woff","woff2"] | Font formats to generate | | fontName | fontello | Font family name in CSS and font filenames | | classPrefix | icon | CSS class prefix for icons | | hashOutput | true | Append content hash to output folder for cache busting |

Features

Font Name (fontName)

Controls the font-family name in CSS and the output filenames.

"fontName": "fontello"     // → fontello.woff2, font-family: "fontello"
"fontName": "myicons"      // → myicons.woff2, font-family: "myicons"

This means you can generate a drop-in replacement for an existing Fontello font — same filenames, same font-family, just upload to CDN.

Class Prefix (classPrefix)

Controls the CSS class prefix for all icons. SVG filename becomes the icon name.

"classPrefix": "icon"      // → .icon-home, .icon-settings, .icon-user
"classPrefix": "pi"        // → .pi-home, .pi-settings, .pi-user

Cache Busting (hashOutput)

When true, the output folder gets a content hash suffix:

fontello-5f3f3c64/
  ├── css/fontello.css
  ├── font/fontello.woff2 ...
  ├── IconTypes.js
  ├── config.json
  └── demo.html

• Same icons → same hash → CDN cache works
• Add/remove/change an SVG → new hash → CDN cache is busted automatically
• Old hashed folders are auto-deleted on regenerate

Set "hashOutput": false for a plain fontello/ folder without hash.

CDN Support (importFontsPath)

Controls the font URL prefix inside the generated CSS.

// Relative (default) — for local hosting
"importFontsPath": "../font/"
// → url('../font/fontello.woff2')

// CDN — for remote hosting
"importFontsPath": "https://cdn.example.com/font/"
// → url('https://cdn.example.com/font/fontello.woff2')

Stroke-to-Fill Conversion

Line/stroke icons (e.g. from Figma, Heroicons) are automatically converted to filled outlines. Icon fonts only support fills — this conversion happens transparently so your stroke-based SVGs work out of the box.

SVG Sanitisation

• Spaces and special characters in filenames are auto-sanitised to hyphens
• <defs>, clip-path, filter, mask elements are stripped
• White background <rect> elements are removed
• Non-path elements (<circle>, <ellipse>, <rect>, <polygon>, <polyline>, <line>) are fully supported

Output

fontello-5f3f3c64/
  ├── css/
  │   └── fontello.css          ← @font-face + all .icon-* classes
  ├── font/
  │   ├── fontello.woff2        ← primary web font
  │   ├── fontello.woff
  │   ├── fontello.ttf
  │   ├── fontello.eot
  │   └── fontello.svg
  ├── IconTypes.js              ← JS constants for icon names
  ├── config.json               ← Fontello-compatible glyph metadata
  └── demo.html                 ← interactive icon browser (search, click to copy)

Open demo.html in a browser to browse all icons, search by name, and click any card to copy its class name.

Usage

HTML

<!-- Load CSS once -->
<link rel="stylesheet" href="fontello/css/fontello.css" />

<!-- Use icons -->
<i class="icon-home"></i>
<i class="icon-settings"></i>
<i class="icon-arrow-right"></i>

React / Next.js

Import the CSS once in your root layout or entry file:

// Option 1: <link> tag (for public/ assets or CDN)
<link rel="stylesheet" href="/assets/fontello/css/fontello.css" />

// Option 2: CSS import (for src/ assets)
import "./assets/fontello/css/fontello.css";

Use icons anywhere:

// Direct class name
<i className="icon-home" />

// With Tailwind — control size and color
<i className="icon-home text-4xl text-blue-500" />

// Dynamic from variable or CMS
<i className={`icon-${iconName} text-2xl`} />

Using IconTypes.js

The generated IconTypes.js provides constants for every icon name:

const IconTypes = {
  HOME: 'home',
  SETTINGS: 'settings',
  ARROW_RIGHT: 'arrow-right',
  // ...
};
export default IconTypes;

Use for consistent, typo-free icon references:

import IconTypes from "./fontello/IconTypes";

<i className={`icon-${IconTypes.HOME}`} />
<i className={`icon-${IconTypes.SETTINGS}`} />

Sizing and Coloring

Icons are a font, so standard text CSS properties control their appearance:

/* Size — use font-size */
.icon-home { font-size: 24px; }
.icon-home { font-size: 2rem; }

/* Color — use color */
.icon-home { color: #335fff; }

/* Tailwind shorthand */
<i class="icon-home text-4xl text-blue-500" />
<i class="icon-home text-6xl text-red-600 hover:text-red-800" />

Programmatic API

const { buildIcons } = require("wmt-polyicon");

const result = await buildIcons({
  svg: "./icons",
  outputFonts: "./dist/fontello/font",
  outputStyles: "./dist/fontello/css/fontello.css",
  outputTypes: "./dist/fontello/IconTypes.js",
  importFontsPath: "../font/",
  fontName: "fontello",
  classPrefix: "icon",
  hashOutput: true,
  formats: ["woff2", "woff", "ttf"]
});

console.log(result.outputDir);
// → ./dist/fontello-a3f7b2c1

CLI Reference

polyicon <command> [options]

Commands:
  init           Create .polyiconrc with defaults and comments
  generate       Generate fonts, CSS, types, and preview

Options:
  -c, --config   Path to config file (default: .polyiconrc)
  -f, --force    Overwrite existing config on init

Examples

# Standard workflow
polyicon init
polyicon generate

# Custom config path
polyicon init --config icons.json
polyicon generate --config icons.json

# Overwrite existing config
polyicon init --force

SVG Guidelines

For best results, your SVG icons should be:

• Single colour — icon fonts are monochrome (colour is applied via CSS)
• Square artboard — e.g. 24×24, 32×32, or any consistent size
• Clean paths — remove masks, filters, clip-paths (auto-stripped but cleaner input = better output)
• Filled or stroked — both work (strokes are auto-converted to fills)

SVG filenames become CSS class names:

mobile-app.svg    → .icon-mobile-app
Web-Development.svg → .icon-Web-Development
AI ML Model.svg   → .icon-AI-ML-Model  (spaces → hyphens)

License

MIT