@twbs/fantasticon

!Logo

Fantasticon

!Screenshot

Easy-to-use, pre-configured CLI tool to generate web-font icon kits from SVG files

$3

Icon-font generation, easy to use and highly configurable.

It also generates TypeScript types, JSON maps of the generated code-points, allowing for a great deal of different usages, e.g. integrating with React type-safe icon components or integration on mobile apps by just combining TTF and JSON generation.

$3

``bash
npm install -g @twbs/fantasticon
`

Use

$3

`bash
fantasticon my-icons -o icon-dist
`

$3

Note: Not all options can be specified through the command line - for formatOptions, pathOptions, getIconId and templates use a configuration file or the JavaScript API.

`text
Usage: fantasticon [options] [input-dir]

Options:
-V, --version output the version number
-c, --config custom config path (default: .fantasticonrc | fantasticonrc | .fantasticonrc.json | fantasticonrc.json | .fantasticonrc.js | fantasticonrc.js)
-o, --output specify output directory
-n, --name base name of the font set used both as default asset name (default: icons)
-t, --font-types specify font formats to generate (default: eot, woff2, woff, available: eot, woff2, woff, ttf, svg)
-g --asset-types specify other asset types to generate (default: css, html, json, ts, available: css, less, scss, sass, html, json, ts)
-h, --font-height the output font height (icons will be scaled so the highest has this height) (default: 300)
--descent the font descent
--normalize [bool] normalize icons by scaling them to the height of the highest icon
-r, --round [bool] setup the SVG path rounding [10e12]
--selector use a CSS selector instead of 'tag + prefix' (default: null)
-p, --prefix CSS class prefix (default: icon)
--tag CSS base tag for icons (default: i)
-u, --fonts-url public URL to the fonts directory (used in the generated CSS)
--debug display errors stack trace (default: false)
--silent run with no logs (default: false)
--help display help for command
`

$3

Some options (specifically, formatOptions, pathOptions and getIconId) cannot be passed to the CLI directly.

To have more control and better readability, you can create a simple configuration file.

By default, fantasticon will look for one of following files in the working directory:

`text
.fantasticonrc | fantasticonrc | .fantasticonrc.json | fantasticonrc.json | .fantasticonrc.js | fantasticonrc.js
`

You can specify a custom --config option with your configuration file path.

Here's an example .fantasticonrc.js:

`js
module.exports = {
inputDir: './icons', // (required)
outputDir: './dist', // (required)
fontTypes: ['ttf', 'woff', 'woff2'],
assetTypes: ['ts', 'css', 'json', 'html'],
fontsUrl: '/static/fonts',
formatOptions: {
// Pass options directly to svgicons2svgfont
woff: {
// Woff Extended Metadata Block - see https://www.w3.org/TR/WOFF/#Metadata
metadata: '...'
},
json: {
// render the JSON human readable with two spaces indentation (default is none, so minified)
indent: 2
},
ts: {
// select what kind of types you want to generate (default ['enum', 'constant', 'literalId', 'literalKey'])
types: ['constant', 'literalId'],
// render the types with ' instead of " (default is ")
singleQuotes: true,
// customise names used for the generated types and constants
enumName: 'MyIconType',
constantName: 'MY_CODEPOINTS'
// literalIdName: 'IconId',
// literalKeyName: 'IconKey'
}
},
// Use a custom Handlebars template
templates: {
css: './my-custom-tp.css.hbs'
},
pathOptions: {
ts: './src/types/icon-types.ts',
json: './misc/icon-codepoints.json'
},
codepoints: {
'chevron-left': 57344, // decimal representation of 0xe000
'chevron-right': 57345,
'thumbs-up': 57358,
'thumbs-down': 57359
},
// Customize generated icon IDs (unavailable with .json config file)
getIconId: ({
basename, // string - Example: 'foo';
relativeDirPath, // string - Example: 'sub/dir/foo.svg'
absoluteFilePath, // string - Example: '/var/icons/sub/dir/foo.svg'
relativeFilePath, // string - Example: 'foo.svg'
index // number - Example: 0
}) => [index, basename].join('_') // '0_foo'
};
`

$3

#### Simple usage

`js
import { generateFonts } from '@twbs/fantasticon';

generateFonts().then(results => console.log('Done', results));
`

#### Options

`js
import { generateFonts } from '@twbs/fantasticon';

generateFonts({
name: 'icons',
fontTypes: [FontAssetType.EOT, FontAssetType.WOFF2, FontAssetType.WOFF],
assetTypes: [
OtherAssetType.CSS,
OtherAssetType.HTML,
OtherAssetType.JSON,
OtherAssetType.TS
],
formatOptions: { json: { indent: 2 } },
templates: {},
pathOptions: {},
codepoints: {},
fontHeight: 300,
round: undefined, // --
descent: undefined, // Will use svgicons2svgfont defaults
normalize: undefined, // --
selector: null,
tag: 'i',
prefix: 'icon',
fontsUrl: null
}).then(results => console.log(results));
`

#### Organising icons

Icon names and className will be generated from a slug of the relative path + basename of each .svg file found in the input directory.

This allows arranging your icons in namespaces, which can be useful if a project uses a large number of icons.

Considering the following ./icons input directory:

`text
icons
├── logo.svg
├── social
│ ├── facebook.svg
│ └── twitter.svg
└── symbol
└── chevron
├── left.svg
└── right.svg
`

Running fantasticon ./icons -o dist will generate a font-set with the following Icon IDs / CSS selectors:
And the generated icon IDs would be:

| Icon ID | CSS selector |
| ---------------------- | ---------------------------- |
| social-facebook | .icon.icon-social-facebook |
| social-twitter | .icon.icon-social-twitter |
| symbol-chevron-left | .icon.icon-chevron-left |
| symbol-chevron-right | .icon.icon-chevron-right |

You can provide a getIconId` function via the configuration file to customize how the icon IDs / CSS selectors are derived from the filepath. The function will receive relative paths to the icon and the input directory as arguments, and must return a unique string to be used as the ID.

$3

The library is currently actively maintained for for Node 16.x.x support or above

$3

PRs are always welcome. If you need help questions, want to bounce ideas or just say hi, join the Discord channel.

$3

Copyright (c) 2020 Tancredi Trugenberger. - Released under the MIT license