Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tancredi/fantasticon

Icon font generation tool
https://github.com/tancredi/fantasticon

Last synced: about 1 month ago
JSON representation

Icon font generation tool

Host: GitHub
URL: https://github.com/tancredi/fantasticon
Owner: tancredi
License: mit
Created: 2020-10-05T01:00:00.000Z (about 4 years ago)
Default Branch: master
Last Pushed: 2024-04-11T05:06:51.000Z (8 months ago)
Last Synced: 2024-04-22T15:24:56.790Z (8 months ago)
Language: TypeScript
Homepage:
Size: 3.31 MB
Stars: 877
Watchers: 7
Forks: 94
Open Issues: 74
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

awesome-luooooob - tancredi/fantasticon - Icon font generation tool (TypeScript)

README

![Logo](https://fantasticon.s3.eu-west-2.amazonaws.com/readme/logo.png)

Fantasticon

![Screenshot](https://fantasticon.s3.eu-west-2.amazonaws.com/readme/screenshot.png)

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

### Intro

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.

### Install

```bash
npm install -g fantasticon
```

## Use

### Quick usage

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

### Command-line

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

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

### Configuration file

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 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'
};
```

### API

#### Simple usage

```js
import { generateFonts } from 'fantasticon';

generateFonts().then(results => 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 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:

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

### Support

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

### Contribute

PRs are always welcome. If you need help questions, want to bounce ideas or just say hi, [join the Discord channel](https://discord.gg/BXAY3Kc3mp).

### License