# gulp-iconfont: a Gulp plugin that turns SVG files into a font

> gulp-iconfont bundles four separate plugins into one Gulp task that reads a directory of SVG icons and emits ttf, eot and woff fonts, with woff2 and svg available on request. The author himself points you at plain SVG icons instead, and the release history shows why that advice is reasonable, since the newest tag is from 2021.

**nfroidure/gulp-iconfont** — Create icon fonts from several SVG icons

- Repository: https://github.com/nfroidure/gulp-iconfont
- Stars: 847 · Forks: 70
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/nfroidure-gulp-iconfont

## What the plugin does, and what the author thinks of it

gulp-iconfont creates icon fonts from several SVG icons. The description is that plain, and the implementation is a Gulp task that takes a glob of SVG files and produces a font family you can reference from CSS.

What makes this project interesting is the warning at the top of the documentation, and the reason behind it. The author says that while the plugin may still be useful for font generation or old browser support, you should consider using SVG icons directly. He explains that when he created gulp-iconfont and its related modules, using SVG icons was simply not realistic for wide browser support, but he was already convinced SVG was the future, and that is why he wanted his SVG source files to sit separated in a folder.

That is a rare kind of README. A maintainer telling you to consider moving away from their own tool, and giving the actual historical reason, is more useful than a pitch. The source separation advice still stands on its own: keeping the SVGs in their own directory means switching away from icon fonts later is a matter of pointing your markup at the files rather than restructuring the project.

The author also links a piece on why using SVG over icon fonts, and describes the whole thing as a great open source journey.

For a buyer of this tool, the practical question is therefore narrow. When is an icon font still the right answer? In practice it is when you have a fixed browser support matrix, when a third party component expects font based icons, or when you need one request and one cached file for a large icon set. If your matrix includes any modern browser and you control the markup, the author's own advice wins.

## One API over four plugins, and how the pipeline is split

The README is explicit that gulp-iconfont bundles several plugins to bring a simpler API, and names them: gulp-svgicons2svgfont, gulp-svg2tff, gulp-ttf2eot and gulp-ttf2woff. It invites you to use them separately if you need more flexibility.

That split maps onto the format conversion chain, which explains why the project also tells you where to file a bug. The SVG icons become an SVG font first, through svgicons2svgfont. From the SVG font, svg2ttf produces a TrueType font, and from the TTF the ttf2eot and ttf2woff steps produce the legacy Embedded OpenType and the WOFF format.

The issue routing follows the same map. If the plugin does not work at all, the issue belongs in this repository. If every font fails to display as expected, it goes to svgicons2svgfont. If only some fonts are damaged, the README asks you to look at the font format the target browser actually uses and then file with the matching conversion project, svg2ttf, ttf2eot or ttf2woff. That is unusually good triage advice for a plugin, and it tells you the failure surfaces are in the individual converters rather than in the wrapper.

The `glyphs` event on the task exposes the generated glyphs and the options, which is the hook for CSS templating. The README notes you can generate CSS automatically with gulp-iconfont-css, a separate project maintained by backflip.

## Installing and wiring the task into a gulpfile

The install is a dev dependency, since a font is a build artifact:

```shell
npm install --save-dev gulp-iconfont
```

The task itself is an ES module import plus a Gulp task, and the README's example is the canonical usage:

```javascript
import iconfont from 'gulp-iconfont';

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

gulp.task('Iconfont', async function () {
  return iconfont('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);
    })
    // If you are using gulp v5, add { encoding: false } option in dest function
    // `.pipe(gulp.dest('www/fonts/', { encoding: false }));`
    .pipe(gulp.dest('www/fonts/'));
});
```

Four details in that snippet carry most of the configuration. The fontName option is required. prependUnicode is described as a recommended option and controls the startUnicode and prependUnicode options passed through to gulp-svgicons2svgfont. The formats array defaults to ttf, eot and woff. The timestamp option, taken from gulp-svg2ttf, is recommended because it keeps builds consistent when you are watching files, which is why the example computes a runTimestamp once.

The Gulp 5 note at the bottom matters if you are on a current Gulp. The commented line shows the change: you need to add { encoding: false } to the dest function, because the older form shown will not work unchanged on Gulp 5.

The glob is a normal path pattern, so the icons live in a directory of your choosing, here assets/icons, and the fonts are written to www/fonts.

## Formats, autohinting and the options that pass through

The formats option is an array with the default value ['ttf', 'eot', 'woff'] and the possible values ['svg', 'ttf', 'eot', 'woff', 'woff2']. Two of those are off by default, and the reasons are given.

SVG fonts are disabled per default because they are deprecated in some, and the README's parenthetical is every, browsers. WOFF2 is disabled because it seems to cause issues on some setup, with a link to issue 64 for the details. Both are one flag away if you need them, which is the right default for a library whose output is consumed by environments you do not control.

The autohint option is a boolean or a string, defaulting to false. If ttfautohint is installed on your system, you may want to auto hint your fonts, but the README warns that this is an experimental and untested feature and to use at least the 0.93 version. If the value is a string it is taken as the path to the ttfautohint binary, otherwise ttfautohint is searched in $PATH. The contributing section points to the dockerized version of TTFAutoHint, and the repository has a Dockerfile you can build with:

```sh
docker build -t ttfautohint .
```

The rest of the option surface is pass-through. The svgicons2svgfont options are available, including fontName, fontWeight, fontStyle, fixedWidth, centerHorizontally, normalize, fontHeight, round, descent, metadata and log. The gulp-svgicons2svgfont options startUnicode and prependUnicode are available, as is the gulp-svg2ttf option timestamp. So the wrapper is a convenience layer over a documented set of options rather than a new configuration format.

## Icon height and the export settings that actually matter

The preparation section is where most of the real world friction with this tool lives, and it is short enough to state plainly. Your SVG icons must have a high enough height, with 500 as a minimum. If you do not want to resize them, you can try to combine the fontHeight and the normalize option to get them into a correct size.

There is a related fix for a different symptom. If some font glyphs are not converted properly, the README says to add the normalize:true option and a fontHeight greater than 1000, with fontHeight: 1001 as the example. The reason for the height requirement is not explained further in the documentation, so treat it as a constraint to satisfy rather than a mechanism to understand.

The export recipes are the other half. For Inkscape: ungroup every shape with Ctrl+Shift+G, convert to paths with Ctrl+Maj+C and merge them with Ctrl++, then save as SVG, preferring the simple SVG file type. For Illustrator, save as SVG with SVG Profiles set to SVG 1.1, Fonts Type set to SVG, Fonts Subsetting set to None, Options Image Location set to Embed, and in Advanced Options the CSS Properties set to Presentation Attributes, Decimal Places set to 1, Encoding set to UTF-8, and the output fewer tspan elements option checked. Leave the rest unchecked.

The two editors produce different files, and the fact that the author documents both at that level of detail tells you how much of the support burden in this tool lands on the person preparing the icons rather than on the plugin.

## A TypeScript rewrite, a version gap and an MIT licence

The repository shows the shape of a project that has been modernised in place. The primary language is TypeScript, the source lives in src with test files alongside it as .test.ts, and the build script compiles with tsc into a dist directory after clearing it with rimraf. A second script, rebuild, uses swc to compile with an es2022 target, which is the fast path and the one used in CI-style workflows. The main entry point in package.json is dist/index.js.

The tooling is modern too. ESLint 10 with a flat config file eslint.config.js, Prettier for formatting, Jest run through an experimental VM modules flag, and husky and lint-staged style hooks implied by the precz script that runs tests, lint, metapak and build before a commit. The metapak section of package.json shows the README itself is generated from templates alongside the package configuration, which is why the file opens with a comment saying it is automatically generated and should not be edited outside the content flags.

The version story is the thing to check. The package.json says version 12.0.0, but the listed GitHub releases are v11.0.1 from January 2021, v11.0.0 from January 2021, and v10.0.3 from June 2019. So the tagged releases trail the published package by a major version, and the repository is not archived with the last push on 2026-05-08. The engine requirement is node >=20.11.1.

The licence is MIT, and the contributing section asks that you agree to publishing under it before pushing code. MIT places no obligation on you beyond keeping the notice, which is the friendly case for a build time dependency. The one caveat is that a font generated from an icon set carries the licence of the icons, not of this plugin.

## Conclusion

Adopt gulp-iconfont if you have a Gulp based build, a real set of SVG sources, and a browser support matrix that still needs a font format, such as a legacy eot target. Do not start a new project on it, because the author recommends using SVG icons directly and the newest GitHub release is v11.0.1 from January 2021 while the package.json already reads 12.0.0. Verify first that your icons meet the minimum height of 500 and are exported as paths, that the formats you need are enabled, and that the Node.js version on your machine satisfies the engine requirement of 20.11.1 or newer.

## FAQ

### How do I install gulp-iconfont?

It is a build time dependency, so the README gives `npm install --save-dev gulp-iconfont`. You then add it to your gulpfile with an import of iconfont from 'gulp-iconfont' and a task that calls it with an SVG glob and a fontName.

### Which font formats does gulp-iconfont produce?

The default formats are ttf, eot and woff, and the possible values also include woff2 and svg. SVG fonts and WOFF2 are off by default, SVG because browsers have deprecated it and WOFF2 because of reported setup issues.

### Why are some of my icon glyphs not converting correctly?

The README says to add the normalize:true option and a fontHeight greater than 1000, for example fontHeight: 1001. It also states that your SVG icons must have a height of at least 500.

### Does gulp-iconfont work with Gulp 5?

With a change. The README notes that if you are using Gulp 5 you need to add the { encoding: false } option in the dest function, and the commented line in the example shows the exact form to use.

### Is gulp-iconfont still maintained?

The repository is not archived and the last push was on 2026-05-08, with the package.json at version 12.0.0. The listed GitHub releases are older, with the newest tag v11.0.1 dated 2021-01-17, so a tagged release and the current package version are not the same thing.

## Sources

- [Issues](https://github.com/nfroidure/gulp-iconfont/issues)
- [License: MIT](https://github.com/nfroidure/gulp-iconfont/blob/main/LICENSE)
- [nfroidure/gulp-iconfont on GitHub](https://github.com/nfroidure/gulp-iconfont)
- [README](https://github.com/nfroidure/gulp-iconfont/blob/main/README.md)
- [Releases](https://github.com/nfroidure/gulp-iconfont/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nfroidure-gulp-iconfont