svgicons2svgfont

You can integrate svgicons2svgfont into your Node.js workflows using the SVGIcons2SVGFontStream class. This class is a stream that accepts SVG files as input and outputs an SVG font.

To use it:

1. Instantiate SVGIcons2SVGFontStream with your desired configuration.
2. Pipe the stream to a write stream to save the resulting font.
3. Create read streams for each icon file.
4. Attach a metadata object to each icon read stream containing the unicode (array of strings) and name (string).
5. Write the icon streams to the font stream.
6. Call .end() on the font stream when finished.

import { SVGIcons2SVGFontStream } from 'svgicons2svgfont';
import { createReadStream, createWriteStream } from 'node:fs';

const fontStream = new SVGIcons2SVGFontStream({
  fontName: 'hello',
});

// Setting the font destination
fontStream
  .pipe(createWriteStream('fonts/hello.svg'))
  .on('finish', function () {
    console.log('Font successfully created!');
  })
  .on('error', function (err) {
    console.log(err);
  });

// Writing glyphs
const glyph1 = createReadStream('icons/icon1.svg');
glyph1.metadata = {
  unicode: ['\uE001\uE002'],
  name: 'icon1',
};
fontStream.write(glyph1);

// Do not forget to end the stream
fontStream.end();

The stream operates in three main phases:

1. Parsing (_transform): As SVGIconStream objects arrive, the stream uses a SAX parser to traverse the SVG elements. It handles transform attributes by maintaining a transformation stack, and converts various SVG shapes (rect, line, polyline, polygon, circle, ellipse, path) into SVGPathData.
2. Bounds Calculation (_flush): Once all icons are parsed, the stream calculates the maximum glyph height and width. If usePathBounds is enabled, it uses the actual bounding box of the paths to determine dimensions.
3. Font Generation (_flush): The stream calculates the final fontWidth, ascent, and descent. It then iterates through all glyphs, applies scaling (including normalize logic), applies vertical symmetry (flipping the Y axis for font coordinates), and centers the paths if requested. Finally, it writes the XML structure for the SVG font.

When instantiating new SVGIcons2SVGFontStream(options), you can provide the following configuration:

• fontName (String, default: 'iconfont'): The font family name.
• fontId (String, default: fontName): The font id.
• fontStyle (String, default: ''): The font style.
• fontWeight (String, default: ''): The font weight.
• fixedWidth (Boolean, default: false): Creates a monospace font based on the largest icon.
• centerHorizontally (Boolean, default: false): Centers glyphs horizontally.
• centerVertically (Boolean, default: false): Centers glyphs vertically.
• normalize (Boolean, default: false): Scales icons to the height of the highest icon.
• preserveAspectRatio (Boolean, default: false): Used with normalize to scale down glyphs if width > height.
• fontHeight (Number, default: MAX(icons.height)): The output font height.
• round (Number, default: 10e12): SVG path rounding.
• descent (Number, default: 0): The font descent (must be a positive value).
• ascent (Number, default: fontHeight - descent): The font ascent.
• metadata (String, default: undefined): Character data for the font metadata (e.g., copyright).
• metadataProvider (Function): A function (file: string, cb: (err: any, metadata: {file: string, name: string, unicode: string[], renamed: boolean}) => void) to determine icon metadata asynchronously.
• log (Function, default: console.log): Custom logging function. Set to function(){} to disable.

The SVGIcons2SVGFontStream constructor accepts a partial configuration object to control how the SVG font is generated.

Key options include:

• fontName: The name of the font family.
• fontId: The ID for the <font> element.
• fixedWidth: If true, all glyphs will have the same horiz-adv-x (the calculated fontWidth).
• descent: The descent value for the font.
• ascent: The ascent value (defaults to fontHeight - descent if not provided).
• round: The rounding precision for path data (defaults to 10e12).
• metadata: A string to be placed inside a <metadata> tag in the output SVG.
• usePathBounds: If true, glyph width and height are calculated based on the actual path bounds rather than the SVG viewBox or attributes.
• normalize: If true, scales glyphs so they all fit within the fontHeight while preserving aspect ratio.
• preserveAspectRatio: Used with normalize to determine scaling logic.
• centerHorizontally / centerVertically: If true, centers the glyph paths within their allocated space.
• fontHeight: The total height of the font (recommended to be $\ge 1000$).
• callback: A function called after the stream is flushed, receiving the array of Glyph objects.

List of available command-line flags for svgicons2svgfont:

Usage: svgicons2svgfont [options] <icons ...>

Options:
  -V, --version               output the version number
  -v, --verbose               tell me everything!
  -o, --output [/dev/stdout]  file to write output to
  -f, --fontName [value]      the font family name you want [iconfont]
  -i, --fontId [value]        the font id you want [fontName]
  -st, --style [value]        the font style you want
  -we, --weight [value]       the font weight you want
  -w, --fixedWidth            creates a monospace font of the width of the largest input icon
  -c, --centerHorizontally    calculate the bounds of a glyph and center it horizontally
  -y, --centerVertically      centers the glyphs vertically in the generated font.
  -n, --normalize             normalize icons by scaling them to the height of the highest icon
  -p, --preserveAspectRatio   used with normalize to scale down glyph if the SVG width is greater than the height
  -h, --height [value]        the output font height [MAX(icons.height)] (icons will be scaled so the highest has
                              this height)
  -r, --round [value]         setup the SVG path rounding [10e12]
  -d, --descent [value]       the font descent [0]
  -a, --ascent [value]        the font ascent [height - descent]
  -s, --startUnicode [value]  the start unicode code point for unprefixed files [0xEA01]
  -u, --prependUnicode        prefix files with their automatically allocated unicode code point
  -m, --metadata              content of the metadata tag
  --help                      display help for command

The following options are available for the svgicons2svgfont command-line interface: