or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Gulp Iconfont

Gulp Iconfont is a TypeScript Gulp plugin that creates icon fonts from SVG icon files. It transforms collections of vector graphics into web fonts that can be deployed across different browsers and platforms, supporting multiple font formats (TTF, EOT, WOFF, WOFF2, SVG).

Package Information

Package Name: gulp-iconfont
Package Type: npm
Language: TypeScript
Installation: npm install --save-dev gulp-iconfont

Core Imports

import gulpIconFont from "gulp-iconfont";
import type { GulpIconFontOptions } from "gulp-iconfont";

For CommonJS:

const gulpIconFont = require("gulp-iconfont");

Basic Usage

import gulp from "gulp";
import gulpIconFont from "gulp-iconfont";

const runTimestamp = Math.round(Date.now() / 1000);

gulp.task('iconfont', function () {
  return gulpIconFont('assets/icons/*.svg', {
    fontName: 'myfont', // required
    prependUnicode: true, // recommended option
    formats: ['ttf', 'eot', 'woff'], // default, 'woff2' and 'svg' are available
    timestamp: runTimestamp, // recommended to get consistent builds when watching files
  })
    .on('glyphs', function (glyphs, options) {
      // CSS templating, e.g.
      console.log(glyphs, options);
    })
    .pipe(gulp.dest('www/fonts/'));
});

Architecture

Gulp Iconfont orchestrates multiple font conversion tools through a unified API that handles the complete pipeline from SVG input to multiple font format outputs:

Stream Processing: Built on Node.js streams with multipipe for complex pipeline orchestration
Font Conversion Pipeline: Integrates gulp-svgicons2svgfont, gulp-svg2ttf, gulp-ttf2eot, gulp-ttf2woff, gulp-ttf2woff2
Format Selection: Conditional processing based on selected output formats
Auto-hinting Support: Optional TTF auto-hinting via external ttfautohint tool
Event System: Emits glyph mapping events for CSS generation workflows

Capabilities

Icon Font Generation

Main function that creates icon fonts from SVG files with comprehensive format support and configuration options.

/**
 * Creates icon fonts from SVG files (default export)
 * @param glob - File path pattern(s) to SVG icon files
 * @param options - Configuration options combining GulpIconFontOptions and SVGIcons2SVGFontOptions
 * @returns A Gulp stream that can be piped and emits 'glyphs' events
 */
export default function gulpIconFont(
  glob: string | string[],
  options: Partial<GulpIconFontOptions> & SVGIcons2SVGFontOptions
): NodeJS.ReadWriteStream;

/**
 * Type definition for gulp-iconfont specific options (exported type)
 */
export type GulpIconFontOptions = {
  /** Array of font formats to generate */
  formats: ('ttf' | 'eot' | 'woff' | 'woff2' | 'svg')[];
  /** Boolean flag for cloning (automatically set based on formats) */
  clone: boolean;
  /** Auto-hinting configuration: false, true, or path to ttfautohint binary */
  autohint: boolean | string;
  /** Generation timestamp for consistent builds */
  timestamp: number;
};

Note: SVGIcons2SVGFontOptions is imported from gulp-svgicons2svgfont and includes the following key options:

fontName (required): Name of the generated font
prependUnicode?: boolean: Prepend unicode to filenames
startUnicode?: number: Starting unicode codepoint (default: 0xEA01)
fontHeight?: number: Height of the font
fontWeight?: number: Font weight
fontStyle?: string: Font style (e.g., 'normal', 'italic')
normalize?: boolean: Normalize glyph sizes
centerHorizontally?: boolean: Center glyphs horizontally
centerVertically?: boolean: Center glyphs vertically
fixedWidth?: boolean: Use fixed width for all glyphs
descent?: number: Font descent value
ascent?: number: Font ascent value
round?: number: Rounding precision for coordinates
metadata?: string: Font metadata
metadataProvider?: any: Metadata provider function

interface Glyph {
  /** Name of the glyph */
  name: string;
  /** Unicode codepoints for the glyph */
  unicode: string[];
  /** Optional color information */
  color?: string;
}

Usage Examples:

import gulp from "gulp";
import gulpIconFont from "gulp-iconfont";

// Basic font generation
gulp.task('iconfont', () => {
  return gulpIconFont('icons/*.svg', {
    fontName: 'myicons',
    formats: ['ttf', 'woff', 'woff2'],
    timestamp: Math.round(Date.now() / 1000)
  })
  .pipe(gulp.dest('dist/fonts/'));
});

// With glyph mapping for CSS generation
gulp.task('iconfont-with-css', () => {
  let glyphs;
  
  return gulpIconFont('icons/*.svg', {
    fontName: 'myicons',
    formats: ['ttf', 'woff', 'woff2'],
    prependUnicode: true,
    normalize: true,
    fontHeight: 1001
  })
  .on('glyphs', (generatedGlyphs, options) => {
    glyphs = generatedGlyphs;
    // Use glyphs data for CSS generation
    console.log('Generated glyphs:', glyphs);
  })
  .pipe(gulp.dest('dist/fonts/'));
});

// With auto-hinting (requires ttfautohint installed)
gulp.task('iconfont-hinted', () => {
  return gulpIconFont('icons/*.svg', {
    fontName: 'myicons',
    formats: ['ttf'],
    autohint: true, // or path to ttfautohint binary
    timestamp: Math.round(Date.now() / 1000)
  })
  .pipe(gulp.dest('dist/fonts/'));
});

Event Handling

The gulp-iconfont stream emits events for accessing generated glyph mappings.

interface GulpIconFontStream extends NodeJS.ReadWriteStream {
  /**
   * Emitted when glyph mappings are generated
   * @param event - Event name 'glyphs'
   * @param handler - Handler function receiving glyphs and options
   */
  on(event: 'glyphs', handler: (glyphs: Glyph[], options: any) => void): this;
}

Usage Example:

gulpIconFont('icons/*.svg', { fontName: 'myicons' })
  .on('glyphs', (glyphs, options) => {
    // Process glyph mappings for CSS generation
    glyphs.forEach(glyph => {
      console.log(`${glyph.name}: ${glyph.unicode[0]}`);
    });
  })
  .pipe(gulp.dest('fonts/'));

Format Configuration

Configure which font formats to generate from the source SVG files.

Available Formats:

'ttf': TrueType Font (included by default)
'eot': Embedded OpenType (included by default, for IE support)
'woff': Web Open Font Format (included by default)
'woff2': Web Open Font Format 2.0 (modern browsers, smaller file size)
'svg': SVG Font (deprecated but available for legacy support)

Usage Examples:

// Default formats (TTF, EOT, WOFF)
gulpIconFont('icons/*.svg', {
  fontName: 'myicons'
});

// Modern browsers only
gulpIconFont('icons/*.svg', {
  fontName: 'myicons',
  formats: ['woff2']
});

// All formats including SVG
gulpIconFont('icons/*.svg', {
  fontName: 'myicons',
  formats: ['svg', 'ttf', 'eot', 'woff', 'woff2']
});

Font Metrics Configuration

Fine-tune font appearance and layout characteristics.

Key Options:

fontHeight: Overall font height (minimum 500, recommended 1000+)
normalize: Normalize glyph sizes for consistent appearance
descent: Font baseline descent value
ascent: Font ascent value above baseline
centerHorizontally: Center glyphs horizontally in their bounds
centerVertically: Center glyphs vertically in their bounds

Usage Example:

gulpIconFont('icons/*.svg', {
  fontName: 'myicons',
  fontHeight: 1001,
  normalize: true,
  centerHorizontally: true,
  descent: 140
});

Note: If some font glyphs aren't converted properly, add normalize: true and a fontHeight greater than 1000.

Unicode Management

Control how Unicode codepoints are assigned to glyphs.

gulpIconFont('icons/*.svg', {
  fontName: 'myicons',
  startUnicode: 0xEA01, // Starting Unicode codepoint
  prependUnicode: true  // Add Unicode to filename
});

When prependUnicode: true, generated files will include Unicode prefixes in their names for easier identification.

Auto-hinting Support

Enable automatic font hinting using ttfautohint (requires external installation).

// Basic auto-hinting (requires ttfautohint in PATH)
gulpIconFont('icons/*.svg', {
  fontName: 'myicons',
  autohint: true,
  formats: ['ttf']
});

// Custom ttfautohint path
gulpIconFont('icons/*.svg', {
  fontName: 'myicons',
  autohint: '/usr/local/bin/ttfautohint',
  formats: ['ttf']
});

Requirements:

ttfautohint must be installed on your system
Use at least ttfautohint version 0.93
Only works with TTF format output