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';

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 

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.

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");

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.

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>

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: