https://github.com/orcunsaltik/iconism
Fonts and web assets generator from svg icons.
https://github.com/orcunsaltik/iconism
eot html json sass scss svg svg-font svg-icons svg-sprite svg-sprites ttf ttf2eot ttf2woff ttf2woff2 woff woff2
Last synced: 4 months ago
JSON representation
Fonts and web assets generator from svg icons.
- Host: GitHub
- URL: https://github.com/orcunsaltik/iconism
- Owner: orcunsaltik
- Created: 2021-01-30T14:14:31.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-07-21T08:45:54.000Z (almost 2 years ago)
- Last Synced: 2025-03-07T08:23:18.979Z (over 1 year ago)
- Topics: eot, html, json, sass, scss, svg, svg-font, svg-icons, svg-sprite, svg-sprites, ttf, ttf2eot, ttf2woff, ttf2woff2, woff, woff2
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/iconism
- Size: 44.9 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# iconism
[](https://github.com/orcunsaltik/iconism/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/iconism)
[](https://www.npmjs.com/package/iconism)
[](https://nodejs.org)
[](LICENSE)
> Modern SVG icon font generator - Create TTF, WOFF, WOFF2, EOT fonts and web assets (CSS, SCSS, HTML, JSON, sprites) from SVG files with TypeScript support.
A complete fonts and web assets generator that searches, optimizes, and merges SVG icon files from multiple directories or configuration files.
## Features
- ✅ Multiple font formats: **SVG, TTF, WOFF, WOFF2, EOT**
- ✅ Web assets: **HTML, CSS, SCSS, SASS, JSON, SVG Sprite**
- ✅ CLI and programmatic API
- ✅ **TypeScript support** with complete type definitions
- ✅ **Modern demo page** with dark mode, search, and copy-to-clipboard
- ✅ **CSS utilities** (size, rotate, flip, spin animations)
- ✅ **SCSS/SASS mixins** for flexible icon usage
- ✅ SVG optimization with SVGO
- ✅ Custom templates support
- ✅ Unicode codepoint mapping
- ✅ Zero configuration defaults
## Requirements
- Node.js >= 18.0.0
## Installation
### Global (CLI)
```bash
npm install -g iconism
```
### Local (API)
```bash
npm install --save-dev iconism
```
## Usage
### TypeScript
iconism comes with full TypeScript support:
```typescript
import iconism, { IconismOptions } from 'iconism';
const options: IconismOptions = {
name: 'myicons',
input: 'src/icons/*.svg',
output: 'dist/fonts',
types: ['woff2', 'woff', 'ttf'],
assets: ['css', 'scss', 'html'],
optimize: true,
};
await iconism(options);
```
### Programmatic API
```javascript
const iconism = require('iconism');
// Basic usage
iconism({
name: 'myicons',
input: 'src/icons/svg',
output: 'dist/fonts',
types: ['woff2', 'woff', 'ttf'],
assets: ['html', 'css'],
height: 512,
descent: 64,
optimize: true,
});
// Async/await
const generate = async () => {
await iconism({
name: 'icons',
input: 'icons/*.svg',
output: 'build',
types: ['woff2', 'woff'],
assets: ['css', 'scss'],
});
console.log('Icons generated!');
};
generate();
```
### Command-line Interface
```bash
iconism --help
Usage: iconism [options]
Convert svg icons to svg, ttf, woff, woff2 and eot font formats and generate web assets.
Options:
-v, --version output the current version
-o, --output output directory
-c, --config configuration file
-f, --fontfamily font family (default: iconfont)
-i, --id font id (default: fontfamily)
-s, --style font style (default: normal)
-W, --weight font weight (default: normal)
-a, --ascent font ascent (default: height - descent)
-d, --descent font descent (default: 0)
-h, --height font height (default: maximum glyph height)
-w, --width font width (default: auto)
-m, --metadata font metadata tag
-r, --round svg path rounding (default: 1)
-b, --begin start unicode codepoint (default: 0xE000)
-t, --types font types (default: woff2, woff, ttf)
-A, --assets assets (default: css, html)
-H, --hash css hash (default: false)
-T, --tag css tag (default: null)
-u, --url font directory url (default: null)
-p, --prefix css prefix class (default: i)
-S, --selector css selector (default: null)
-O, --optimize optimize svgs with svgo
-D, --debug output all information
-e, --help display help for command
```
#### CLI Examples
```bash
# Generate fonts from directory
iconism -o dist/fonts src/icons/*.svg
# Generate with specific types
iconism -o dist -t woff2 woff -A css scss src/icons/*.svg
# Use configuration file
iconism -c iconism.config.js -o dist src/icons/*.svg
```
## API Reference
### iconism(options)
| Option | Type | Default | Description |
| -------------- | ----------------- | ------------------------ | ---------------------------------------- |
| **`input`** | `string\|array` | **`* required`** | SVG files directories, files or config |
| **`output`** | `string` | **`* required`** | Output directory |
| **`config`** | `string` | `null` | Configuration file path |
| **`name`** | `string` | `iconism` | Font family name |
| **`id`** | `string` | `option.name` | Font ID |
| **`style`** | `string` | `normal` | Font style |
| **`weight`** | `integer\|string` | `400` | Font weight |
| **`height`** | `integer` | `max glyph height` | Font height |
| **`width`** | `integer` | `auto` | Font width |
| **`ascent`** | `integer` | `height - descent` | Font ascent |
| **`descent`** | `integer` | `0` | Font descent |
| **`metadata`** | `string` | `null` | Font metadata / copyright |
| **`round`** | `integer` | `1` | SVG path rounding (0-99) |
| **`begin`** | `integer` | `0xE000` | First glyph unicode codepoint |
| **`types`** | `array` | `['woff2','woff','ttf']` | Font types to generate |
| **`assets`** | `array` | `['html','css']` | Web assets to generate |
| **`hash`** | `boolean` | `false` | Add hash to CSS & font for cache busting |
| **`tag`** | `string` | `null` | CSS tag |
| **`url`** | `string` | `null` | Font directory URL in CSS |
| **`prefix`** | `string` | `i` | CSS class prefix |
| **`selector`** | `string` | `null` | CSS selector |
| **`optimize`** | `boolean` | `true` | Optimize SVG files with SVGO |
| **`svgo`** | `object` | `null` | Custom SVGO options |
| **`debug`** | `function\|bool` | `() => {}` | Debug logging function |
## Input Options
### Directory
```javascript
iconism({
input: 'src/icons',
output: 'dist',
});
```
### Multiple Directories and Files
```javascript
iconism({
input: ['src/icons', 'assets/svg', 'icons/arrow.svg', 'icons/check.svg'],
output: 'dist',
});
```
### JSON Configuration File
```javascript
iconism({
input: 'icons/config.json',
output: 'dist',
});
```
**icons/config.json:**
```json
[
{
"name": "arrow-down",
"unicode": "\uE100",
"path": "icons/arrow-down.svg"
},
{
"name": "arrow-up",
"unicode": "\uE101",
"path": "icons/arrow-up.svg"
}
]
```
### Enhanced JSON Output
When generating JSON assets, you get rich metadata:
```json
{
"name": "myicons",
"version": "1.0.0",
"prefix": "i",
"icons": {
"arrow-down": {
"unicode": 57600,
"hex": "e100",
"character": "",
"className": "i-arrow-down"
},
"arrow-up": {
"unicode": 57601,
"hex": "e101",
"character": "",
"className": "i-arrow-up"
}
}
}
```
### Inline Configuration
```javascript
iconism({
input: [
{
name: 'plus',
unicode: '\uE100',
d: 'M7,9H4V7H7V4H9V7h3V9H9v3H7Z',
width: 512,
height: 512,
viewBox: '0 0 512 512',
},
{
name: 'minus',
unicode: '\uE101',
path: 'icons/minus.svg',
},
],
output: 'dist',
});
```
## Advanced Configuration
### CSS Utilities
Generated CSS includes helpful utility classes:
```css
/* Size utilities */
.i-sm {
font-size: 0.75em;
}
.i-lg {
font-size: 1.25em;
}
.i-xl {
font-size: 1.5em;
}
.i-2x {
font-size: 2em;
}
.i-3x {
font-size: 3em;
}
/* Rotate utilities */
.i-rotate-90 {
transform: rotate(90deg);
}
.i-rotate-180 {
transform: rotate(180deg);
}
.i-rotate-270 {
transform: rotate(270deg);
}
/* Flip utilities */
.i-flip-horizontal {
transform: scaleX(-1);
}
.i-flip-vertical {
transform: scaleY(-1);
}
```
**Usage:**
```html
```
### SCSS Mixins
Generated SCSS includes powerful mixins:
```scss
// Use icon by name
.my-button {
@include icon('arrow-down');
@include icon-size(1.5rem);
@include icon-rotate(45);
}
// Flip icon
.back-button {
@include icon('arrow-right');
@include icon-flip(horizontal);
}
// Spin animation
.loading-icon {
@include icon('spinner');
}
.loading-icon.i-spin {
animation: i-spin 2s linear infinite;
}
```
### Modern Demo Page
The generated HTML demo includes:
- 🌙 **Dark mode** with persistent preference
- 🔍 **Real-time search** - Filter icons instantly
- 📋 **Copy to clipboard** - Click any icon to copy its class name
- 📱 **Responsive design** - Works on all devices
- ⌨️ **Keyboard shortcuts** - `/` to search, `Esc` to clear
- 📊 **Live stats** - See total and visible icon counts
- 🎨 **Grid/List views** - Toggle between layouts
## Advanced Configuration
Create an `iconism.config.js` file for advanced options:
```javascript
module.exports = {
name: 'custom-icons',
input: 'src/icons',
output: 'dist/fonts',
types: ['woff2', 'woff', 'ttf'],
assets: ['sass', 'scss', 'sprite'],
templates: {
sprite: 'templates/sprite.ejs',
},
font: {
names: {
svg: '%name%-svg',
woff2: '%name%-webfont',
},
exports: ['woff2', 'woff', 'ttf'],
},
asset: {
names: {
sprite: '%name%-sprite',
},
exports: ['sass', 'scss', 'sprite'],
},
svgo: {
plugins: [
{ name: 'mergePaths', params: { force: false } },
{ name: 'convertShapeToPath', params: { convertArcs: false } },
],
},
};
```
Then run:
```bash
iconism -c iconism.config.js
```
## Changelog
### v2.0.1 (2025)
- 🚀 Updated SEO-friendly package description
- 🚀 Enhanced keywords for better discoverability
- 📚 Updated README with improved formatting
### v2.0.0 (2024)
#### 🚨 Breaking Changes
- **BREAKING:** Requires Node.js 18+
#### ✨ New Features
- **TypeScript Support:** Complete type definitions (`iconism.d.ts`)
- **Modern Demo Page:**
- Dark mode with localStorage persistence
- Real-time icon search and filtering
- Copy to clipboard functionality
- Grid and list view toggles
- Keyboard shortcuts (`/` for search, `Esc` to clear)
- Live icon statistics
- Responsive mobile-first design
- **CSS Utilities:** Size, rotate, flip, and spin animations
- **SCSS/SASS Mixins:** `@include icon()`, `@include icon-size()`, `@include icon-rotate()`, `@include icon-flip()`
- **Enhanced JSON Output:** Rich metadata with unicode, hex, character, and className
#### 🐛 Bug Fixes
- **CRITICAL:** Fixed SVG sprite closing tag bug (`` → ``)
- Fixed 87 ESLint issues across the codebase
- Fixed async Promise executor anti-patterns (7 instances)
- Fixed path concatenation issues (8 instances, now using `path.join()`)
- Fixed tab/space inconsistencies (50+ instances)
- Fixed mixed operator precedence issues (6 instances)
#### 📦 Dependency Updates
- Updated njfs: 1.2.5 → 2.0.0
- Updated svg2ttf: 5.1.0 → 6.0.3
- Updated ttf2eot: 2.0.0 → 3.1.0
- Updated ttf2woff: 2.0.2 → 3.0.0
- Updated ttf2woff2: 4.0.2 → 5.0.0
- Updated svgo: 2.2.2 → 2.8.0
- Updated ejs: 3.1.6 → 3.1.10
- Updated xml2js: 0.4.23 → 0.6.2
#### 🔧 Development
- Added Prettier for consistent code formatting
- Modern ESLint 8 configuration with standard config
- Travis CI → GitHub Actions (Node 18/20/22)
- Added `.vscode/settings.json` for better IDE support
- Comprehensive `.prettierrc` and `.editorconfig`
#### 📚 Documentation
- Completely rewritten README with modern examples
- Added TypeScript usage examples
- Added CSS utilities documentation
- Added SCSS mixins documentation
- Added demo page features documentation
- Updated badges (CI, npm version, downloads)
### v1.2.3 (2021)
- Previous stable release
## Migration from v1.x
```javascript
// v1.x - Still works in v2.x
iconism({
input: 'icons',
output: 'dist',
});
// v2.x - Now requires Node.js 18+
// All other APIs remain the same
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Troubleshooting
When you encounter a problem, please [open an issue](https://github.com/orcunsaltik/iconism/issues).
## Author
**Orçun Saltık**
- GitHub: [@orcunsaltik](https://github.com/orcunsaltik)
- Email: saltikorcun@gmail.com
## License
[MIT](LICENSE) © Orçun Saltık