fantasticon

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 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.

`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, 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:

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 tosvgicons2svgfontwoff: { // 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.jsonconfig 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

`ts import { generateFonts } from 'fantasticon';

const results = await generateFonts();

console.log('Done', results);`

#### Options

`js import { generateFonts } from '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 usesvgicons2svgfontdefaults 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:

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

Running fantasticon ./icons -o distwill 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

!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.

$3

``bash npm install -g 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.

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

`$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:

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

Here's an example .fantasticonrc.js:

`$3`

#### Simple usage

`ts import { generateFonts } from 'fantasticon';

const results = await generateFonts();

console.log('Done', results);`

#### Options

`js import { generateFonts } from 'fantasticon';

#### 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:

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

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

$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.