\n Easy-to-use, pre-configured CLI tool to generate web-font icon kits from SVG files\n
\n\n
\n \n \n
\n\n### Intro\n\nIcon-font generation, easy to use and highly configurable.\n\nIt 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.\n\n### Install\n\n```bash\nnpm install -g fantasticon\n```\n\n## Use\n\n### Quick usage\n\n```bash\nfantasticon my-icons -o icon-dist\n```\n\n### Command-line\n\n**Note:** Not all options can be specified through the command line - for `formatOptions`, `pathOptions`, `getIconId` and `templates` use a [configuration file](#configuration-file) or the JavaScript [API](#api).\n\n```\nUsage: fantasticon [options] [input-dir]\n\nOptions:\n -V, --version output the version number\n -c, --config custom config path (default: .fantasticonrc | fantasticonrc | .fantasticonrc.json | fantasticonrc.json | .fantasticonrc.js | fantasticonrc.js)\n -o, --output specify output directory\n -n, --name base name of the font set used both as default asset name (default: icons)\n -t, --font-types specify font formats to generate (default: eot, woff2, woff, available: eot, woff2, woff, ttf, svg)\n -g --asset-types specify other asset types to generate (default: css, html, json, ts, available: css, scss, sass, html, json, ts)\n -h, --font-height the output font height (icons will be scaled so the highest has this height) (default: 300)\n --descent the font descent\n --normalize [bool] normalize icons by scaling them to the height of the highest icon\n -r, --round [bool] setup the SVG path rounding [10e12]\n --selector use a CSS selector instead of 'tag + prefix' (default: null)\n -p, --prefix CSS class prefix (default: icon)\n --tag CSS base tag for icons (default: i)\n -u, --fonts-url public URL to the fonts directory (used in the generated CSS)\n --debug display errors stack trace (default: false)\n --silent run with no logs (default: false)\n --help display help for command\n```\n\n### Configuration file\n\nSome options (specifically, `formatOptions`, `pathOptions` and `getIconId`) cannot be passed to the CLI directly.\n\nTo have more control and better readability, you can create a simple configuration file.\n\nBy default, `fantasticon` will look for one of following files in the working directory:\n\n```\n.fantasticonrc | fantasticonrc | .fantasticonrc.json | fantasticonrc.json | .fantasticonrc.js | fantasticonrc.js\n```\n\nYou can specify a custom `--config` option with your configuration file path.\n\nHere's an example `.fantasticonrc.js`:\n\n```js\nmodule.exports = {\n inputDir: './icons', // (required)\n outputDir: './dist', // (required)\n fontTypes: ['ttf', 'woff', 'woff2'],\n assetTypes: ['ts', 'css', 'json', 'html'],\n fontsUrl: '/static/fonts',\n formatOptions: {\n // Pass options directly to `svgicons2svgfont`\n woff: {\n // Woff Extended Metadata Block - see https://www.w3.org/TR/WOFF/#Metadata\n metadata: '...'\n },\n json: {\n // render the JSON human readable with two spaces indentation (default is none, so minified)\n indent: 2\n },\n ts: {\n // select what kind of types you want to generate (default `['enum', 'constant', 'literalId', 'literalKey']`)\n types: ['constant', 'literalId'],\n // render the types with `'` instead of `\"` (default is `\"`)\n singleQuotes: true,\n // customise names used for the generated types and constants\n enumName: 'MyIconType',\n constantName: 'MY_CODEPOINTS'\n // literalIdName: 'IconId',\n // literalKeyName: 'IconKey'\n }\n },\n // Use a custom Handlebars template\n templates: {\n css: './my-custom-tp.css.hbs'\n },\n pathOptions: {\n ts: './src/types/icon-types.ts',\n json: './misc/icon-codepoints.json'\n },\n codepoints: {\n 'chevron-left': 57344, // decimal representation of 0xe000\n 'chevron-right': 57345,\n 'thumbs-up': 57358,\n 'thumbs-down': 57359\n },\n // Customize generated icon IDs (unavailable with `.json` config file)\n getIconId: ({\n basename, // `string` - Example: 'foo';\n relativeDirPath, // `string` - Example: 'sub/dir/foo.svg'\n absoluteFilePath, // `string` - Example: '/var/icons/sub/dir/foo.svg'\n relativeFilePath, // `string` - Example: 'foo.svg'\n index // `number` - Example: `0`\n }) => [index, basename].join('_') // '0_foo'\n};\n```\n\n### API\n\n#### Simple usage\n\n```ts\nimport { generateFonts } from 'fantasticon';\n\nconst results = await generateFonts();\n\nconsole.log('Done', results);\n```\n\n#### Options\n\n```js\nimport { generateFonts } from 'fantasticon';\n\ngenerateFonts({\n name: 'icons',\n fontTypes: [FontAssetType.EOT, FontAssetType.WOFF2, FontAssetType.WOFF],\n assetTypes: [\n OtherAssetType.CSS,\n OtherAssetType.HTML,\n OtherAssetType.JSON,\n OtherAssetType.TS\n ],\n formatOptions: { json: { indent: 2 } },\n templates: {},\n pathOptions: {},\n codepoints: {},\n fontHeight: 300,\n round: undefined, // --\n descent: undefined, // Will use `svgicons2svgfont` defaults\n normalize: undefined, // --\n selector: null,\n tag: 'i',\n prefix: 'icon',\n fontsUrl: null\n}).then(results => console.log(results));\n```\n\n#### Organising icons\n\nIcon names and className will be generated from a slug of the relative path + basename of each `.svg` file found in the input directory.\n\nThis allows arranging your icons in namespaces, which can be useful if a project uses a large number of icons.\n\nConsidering the following `./icons` input directory:\n\n```\nicons\n├── logo.svg\n├── social\n│ ├── facebook.svg\n│ └── twitter.svg\n└── symbol\n └── chevron\n ├── left.svg\n └── right.svg\n```\n\nRunning `fantasticon ./icons -o dist` will generate a font-set with the following Icon IDs / CSS selectors:\nAnd the generated icon IDs would be:\n\n| Icon ID | CSS selector |\n| ---------------------- | ---------------------------- |\n| `social-facebook` | `.icon.icon-social-facebook` |\n| `social-twitter` | `.icon.icon-social-twitter` |\n| `symbol-chevron-left` | `.icon.icon-chevron-left` |\n| `symbol-chevron-right` | `.icon.icon-chevron-right` |\n\nYou 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.\n\n### Support\n\nThe library is currently actively maintained for for Node 16.x.x support or above\n\n### Contribute\n\nPRs are always welcome. If you need help questions, want to bounce ideas or just say hi, [join the Discord channel](https://discord.gg/BXAY3Kc3mp).\n\n### License\n\nCopyright (c) 2026 Tancredi Trugenberger. - Released under the [MIT license](https://github.com/tancredi/fantasticon/blob/master/LICENSE)\n","readmeFilename":"README.md","users":{"flumpus-dev":true}}
![\"Test](\"https://github.com/tancredi/fantasticon/workflows/Test/badge.svg\"){kind=icon}
\n ![\"Release](\"https://github.com/tancredi/fantasticon/workflows/Release/badge.svg\"){kind=icon}
\n