node package manager


Middleware to serve up web fonts.


Connect/Express font serving middleware. Why? Because Google's font CDN is slow and slow page loads cause users to leave your site.

The middleware looks for requests (expressed in Express terminology):


An example of a match is:


When this route is matched, connect-fonts will generate a CSS response with @font-face declarations that are tailored to the user's browser.


  1. Include connect-fonts in a node module.
const font_middleware = require("connect-fonts");
  1. Include the font packs that you want to serve.
const opensans = require("connect-fonts-opensans");
  1. Add a middleware by calling the setup function.
      fonts: [ opensans ],
      allow_origin: "",
      ua: "all",
      maxage: 180 * 24 * 60 * 60 * 1000   // 180 days 

fonts - array of font packs. allow_origin - optional - origin to set in the Access-Control-Allow-Origin header. Defaults to undefined. ua - optional - force a user-agent. "all" means serve up all font types to all users. If not specified, the user's user-agent header will be used to send the user only the fonts that their user-agent support. Defaults to all. maxage - optional - provide a max-age in milliseconds for http caching. Defaults to 0. compress - optional - Whether to compress the CSS/font output. Defaults to false.

  1. Add a link tag to include the font CSS. To serve a default, non-locale specific font, include a CSS link that contains the name of the font:
<link href="/opensans-regular/fonts.css" type="text/css" rel="stylesheet">
  1. Set your CSS up to use the new font by using the correct font-family.
    body {
      font-family: 'Open Sans', 'sans-serif', 'serif';

Advanced Usage

Fonts located on another domain (CDN)

It is possible to specify a host where fonts are located. This is useful if font files are located on another domain.

      fonts: [ opensans ],
      host: "",
      allow_origin: "",
      ua: "all",
      maxage: 180 * 24 * 60 * 60 * 1000   // 180 days 

Locale optimised fonts

If a font pack contains locale optimised fonts, these can be requested by prepending the locale name before the font list in the fonts.css request.

<link href="/en/opensans-regular/fonts.css" type="text/css" rel="stylesheet">

scripts/subset from connect-fonts-tools can be used to create locale-optimised subsets.

Programatically generate CSS for use in build steps

One of the easiest ways to speed up your site is to minimize the number of resources that are requested. The @font-face CSS provided by fonts.css can be fetched programatically and concatinated with other site CSS during a build step.

var fontMiddleware = connect_fonts.setup(...);
// `ua` - user agent. Use 'all' for a CSS bundle that is compatible with all browsers. 
// `lang` - language. generate_css can be called once for each served language, or 
//            "default" can be specified 
// `fonts` - array of font names - e.g. ["opensans-regular", "opensans-italics"] 
fontMiddleware.generate_css(ua, lang, fonts, function(err, css) {
  var css_output_path = path.join(output_dir, dep);
  var css_output_dir = path.dirname(css_output_path);
  // create any missing directories. 
  // finally, write out the file. 
  fs.writeFileSync(css_output_path, css.css, "utf8");

Direct access to font files

Once connect fonts setup function is called, a map of URLs=>paths can be retreived using fontMiddleware.urlToPaths. This information can be used in a build step for tools like connect-cachify that need access to the font file to create an caching hash.

Create a Font Pack

A font pack is an npm module like any other node library. Creating a new font pack is similar to creating any npm module.

  1. Install connect-fonts-tools and run its scripts/setup utility.
npm install connect-fonts-tools
cd node_modules/connect-fonts-tools
  1. Create a font pack target directory
mkdir <target_path>
  1. Call scripts/create_fontpack from connect-font-tools with the source directory, the target directory, and the pack name.
connect-fonts-tools/scripts/create_fontpack --pn <pack_name> --sp <source_path> --tp <target_path>

If the font pack is for public use, specify the additional parameters to be placed inside the font pack's package.json and files.

connect-fonts-tools/scripts/create_fontpack --pn <pack_name> --ph <pack_homepage_url> --pr <pack_repo_url> --pb <pack_bugtracker_url> --sp <source_path> --tp <target_path>
  1. Check your font pack. script/check_font_pack.js is a basic font pack linter. It will check whether pack configuration is sane and if all expected font files are available. To use it, call check_font_pack.js with the absolute path to the font pack's configuration file.
script/check_font_pack.js ~/development/connect-fonts-opensans/index.js
  1. If the font pack is for public use, publish it to the npm repository
cd <target_path>
npm publish
  1. Install the pack using npm into your project:
npm install <pack_name>

If the font pack is not to be published to the npm repository, it can be installed to another local project directory:

cd <target_project_dir>
npm install <font_pack_directory>


Get involved:

MOAR font packs! See connect-fonts-tools for tools to make this easy. connect-fonts-opensans is an example of a finished font pack.

Any updates to connect-fonts are appreciated. All submissions will be reviewed and considered for merge.


This software is available under version 2.0 of the MPL: