subset-iconfont

Subset multiple iconfont packages and generate CSS/SCSS.

Features

• Subset from multiple iconfont npm packages, including FontAwesome Free fonts, Material Design Icons, Bootstrap Icons and Google Material Icons;
• Supported output font formats: woff2, woff, eot, ttf;
• Auto generate font LICENSE files for font used;
• Auto generate FontAwesome styled CSS/SCSS, which means the subset icons can be used like FontAwesome icons, under FontAwesome free license;
• Auto generate metadata of icons used;
• Allow customizing (i.e., removing unwanted) FontAwesome CSS/SCSS components;
• Tested on linux and windows.

Installation

npm install --save-dev subset-iconfont

Basic Usage

Subset from multiple iconfonts, and combine the css/scss files (Combination mode, see Standalone mode below), for example:

// npm install -D @fortawesome/fontawesome-free @mdi/font @mdi/svg

import { subsetIconfont, MdiProvider, FaFreeProvider } from 'subset-iconfont';

const mdi = new MdiProvider(['plus', 'circle', 'check']),
  fa = new FaFreeProvider(['clock', '500px']);

subsetIconfont([mdi, fa], './outputDir', { formats: ['ttf', 'woff2'] }).then(
  (result) => {
    console.log('Done!');
  }
);

Demo

Run

npm install --save-dev @fortawesome/fontawesome-free @mdi/font @mdi/svg bootstrap-icons material-icons @material-design-icons/svg
npm run demo

See results in output and output-standalone, and open the index.html files in browser to see the usage of the generated icons.

ProviderConstructor

The process runs on a list of ProviderInstance, or ProviderConstructor instances. ProviderConstructors are constructors we created for the purpose of subsetting different iconfont in a consistent way. Available ProviderConstructors include:

• FaFreeProvider
  • Source: FontAwesome Free fonts by @fontawesome
  • License: Font Awesome Free License
  • Required npm package: @fortawesome/fontawesome-free
  • styles: solid, regular, brands allowed by the Fontawesome Free license
• Fa4Provider
  • Source: FontAwesome 4 by @fontawesome
  • License: Same with FaFreeProvider, need download manually from Font Awesome Free License.
  • Required npm package: font-awesome
  • styles: no styles.
• MdiProvider
  • Source: Material Design Icons by Austin Andrews
  • License: MIT license
  • Required npm packages: @mdi/font and @mdi/svg
  • Note: many of the icons have a outline variant, which will be included in the result when subsetting. For example, plus-outline will also included if plus is to be subset. We do not use a outline style because the variants were assigned different unicode values.
• BiProvider
  • Source: Bootstrap Icons by The Bootstrap Authors
  • License: MIT license
  • Required npm package: bootstrap-icons.
  • styles: outlined, filled, rounded, sharp and two-tone
• MiProvider
  • Source: Google Material Icons npm packages unofficially maintained @marella
  • License: Apache License version 2.0
  • Required npm packages: material-icons and @material-design-icons/svg

Note: For provider with styles properties, the program will extract all available styles of that icon.

The syntax to create a ProviderInstance is:

ProviderConstructor(subset: subsetItem[], options?: ProviderOptions)

subset

• Type: array of string
• Descriptions: the icon names that are expected to be subset from the provider. Non-existing icons will be ignored and warn in the log.
• Note: To extract all the icons available, use ['__all__'] as the subset.

options

• Type: ProviderOptions

Allowed members:

formats

• Type: array,
• Default: ['woff2', 'ttf'],
• Possible values: ttf, eot, woff, woff2,
• Description: Font file formats to generate.

fontName

• Type: string
• Default: the value from the provider.
• Description: The font family name you want to use.

fontFileName

• Type: string
• Default: The value from the provider.
• Description: A string which can be used a file name, which will be used as:
  • The basename of the font file, for provider without multiple styles;
  • The basename of the css file which included the main style and definitions of icons;
  • The major part of the basename of the font-face css file, for providers without multiple styles;
• Note: For providers with multiple styles, the font file name will be the concatenation of cssPrefix property of the provider, style used and fontWeight of that style, while the font-face file base name will be the concatenation of cssPrefix and style.

prefix

• Type: string
• Default: The value from the provider.
• Description: The prefix in the css class when using the icon.

webfontDir

• Type: string
• Default: webfonts
• Description: The name of the sub-directory where the font files are expected be written to.

generateMinCss

• Type: boolean
• Default: true
• Description: Whether generate a minified css version for each css files generated.

generateCssMap

• Type: boolean
• Default: true
• Description: Whether generate a .map file for each css files generated.

LoggerOptions

• Type: winston.LoggerOptions
• Default: {level: 'warn'}
• Description: The options of winston logger. We implemented a Console transport, but that can be extended. See winston for more information.

writeOutFiles

• Type: array
• Default: ['webfonts', 'scss', 'css', 'licenses', 'web', 'metadata']
• Description: The categories of files which will be physically written to disk:
  • webfonts: The font files generated
  • scss: The scss files
  • css: The css files
  • license: The LICENSE file of the font used
  • web: An index.html file which presenting all the subset icons in a web page
  • metadata: The metadata of all the subset icons

addHashInFontUrl

• Type: boolean
• Default: true
• Description: Whether adding font file hash in font face CSS/SCSS file. This is useful to update client caching of font files.

cssChoices

• Type: array
• Default: ['sizing', 'fixed-width', 'list', 'bordered', 'animated', 'rotated', 'flipped', 'stacked', 'inverse', 'screen-reader']
• Description: The FontAwesome CSS/SCSS components that will be generated. This is useful when you want to minimize the generated results. For example, you can set the value to [] if you don't need extra CSS features provided by FontAwesome.

API

Standalone mode

ProviderInstance.makeFonts(outputDir): Promise<MakeFontResult>

By Standalone, we mean subset from a ProviderInstance.

outputDir

• Type: string
• Description: A path string where the output files are expected to be written to.

For example:

// npm install -D @mdi/font @mdi/svg

import { MdiProvider } from 'subset-iconfont';

const mdi = new MdiProvider(['plus', 'circle', 'check'], {
  formats: ['ttf', 'woff2'],
});

mdi.makeFonts('./outputDir').then((result) => {
  console.log('Done!');
});

Combination mode

subsetIconfont(providerInstances: ProviderInstance[], outputDir: string, options?: SubsetOptions): Promise<MakeFontResult>

providerInstances

• Type: array
• Description: An array of ProviderInstance instances

outputDir

• Type: string
• Description: A path string where the output files are expected to be written to.

options

• Type: SubsetOptions

The options of type SubsetOptions largely replicates the options (of type ProviderOptions) when creating a ProviderInstance , with an extra option outputPackages.

outputPackages

• Type: boolean
• Default: false
• Description: Whether output the subset result of each iconfont. If true, there will be a packages directory which contains all the subset results of the combined packages.

If not configured, fontName will use "Subset Iconfont", and prefix will use "si", and fontFileName will use "subset-iconfont", as default value.

Notice: fontName, prefix under combination mode will override the options set in ProviderInstances so that we can use all subset icons in a consistent way irrespective of which icon comes from which provider (package).

Result

• Type: MakeFontResult

Members include:

prefix

• Type: string
• Description: The css class prefix when using the generated CSS/SCSS.

fontName

• Type: string
• Description: see the description of fontName in ProviderOptions.

formats

• Type: array of string
• Description: the format of fonts generated.

fontFileName

• Type: string
• Description: see the description of fontFileName in ProviderOptions.

icons

• Type: object
• Description: The metadata of all icons from the subset process.

webfontDir

• Type: string
• Description: The name of the sub-directory where the font files are expected to exist in.

generateMinCss

Same as generateMinCss in ProviderOptions.

generateSourceMap

Same as generateSourceMap in ProviderOptions.

license

• Type: string or null
• Description: The content of the font license in standalone mode (for a single subsetProvider). The value will be null under combination mode.

logger

• Type: winston Logger object
• Description: The logger used in the process

blobObject

• Type: array of objects
• Description: Each of the object contains the generated category (in terms of webfonts, SCSS, CSS and font LICENSES) of the blob, and the information including the dir, name and data (string or Buffer).

writeOutFiles

See writeOutFiles in ProviderOptions.

fontWeightDefault

• Type: string or number
• Description: The default fontWeight used in the generated CSS.

Usage of Icons generate

See generated index.html and FontAwesome free documentation for details

Roadmap

• Extend the use case beyond commonJS, for example, react.js, and that's why we've prepared the glyph data of each icon;
• More tests;
• Improved docs;
• Better webpage (index.html) presentation, include search and select abilities.

Contribution

Feel free to contribute under the MIT license.

Changelog

Check our Changelog

License

Check our License