Connect/Express Font Serving Middleware

Connect-fonts is a font serving middleware for Connect/Express.

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


An example is:


When a match is made, connect-fonts generates a CSS response with @font-face declarations tailored to the user's browser.


  1. Install the middleware
    npm install connect-fonts
  2. Install a font-pack
    npm install connect-fonts-opensans
  3. Include connect-fonts in your server code.
    const font_middleware = require("connect-fonts");
  4. Include the font packs.
    const opensans = require("connect-fonts-opensans");
  5. Add a middleware by calling the setup function.
      fonts: [ opensans ],
      allow_origin: "",
      maxage: 180 * 24 * 60 * 60 * 1000,   // 180 days
      compress: true
    array of font packs
    origin to set in the Access-Control-Allow-Origin header
    provide a max-age in milliseconds for http caching, defaults to 0.
    If true, compresses CSS and compressable fonts
    (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.
  6. 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"/ >
  7. 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

Locale optimised fonts

Locale optimised fonts 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"/ >
Locale optimised fonts are included with some font packs, but if not, scripts/subset from connect-fonts-tools can be used to create them.

Programatically generate CSS for use in build steps

One of the easiest ways to speed up your site is to minimize the number of external resources that are requested. The @font-face CSS provided by fonts.css can be generated programatically and concatinated with other site CSS during a build step.
// font_middleware.setup has already been called.
// `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"]
font_middleware.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

After the middleware's setup function is called, a map of font URLs to paths can be retreived using font_middleware.urlToPaths. This information is useful to tools like connect-cachify that need access to the font file to create a caching hash.

Creating 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
  2. 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>
  3. Check whether the font pack configuration is sane and if all font files are available by calling the built in linter, script/check_font_pack.js. 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
  4. If the font pack is for public use, publish it to the npm repository

    cd <target_path>
    npm publish

  5. Install the pack using npm into your project:

    npm install <pack_name>

    Local font packs can be installed to another local project directory:

    cd <target_project_dir>
    npm install <font_pack_directory>


The source is available on GitHub at The npm module can be installed using npm install connect-fonts.


Getting involved

MOAR font packs! See connect-fonts-tools for tools to make font pack creation 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: