# node-font-face-generator

> Generate language/browser dependent @font-face CSS declarations

Latest version **0.1.9** (published 2017-04-18) · MPL-2.0 license · 0 weekly downloads

## Install

```sh
npm install node-font-face-generator
pnpm add node-font-face-generator
yarn add node-font-face-generator
bun add node-font-face-generator
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.9 |
| Published | 2017-04-18 |
| First published | 2012-09-18 |
| Weekly downloads | 0 |
| License | MPL-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.10.0 |
| Dependencies | 2 |
| Known vulnerabilities | 0 (+5 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 12 |
| Maintainers | 6a68, fmarier, ozten, seanmonstar, stomlinson, vladikoff, zaach |
| Keywords | font, font-face, CSS |

## Links

- npm: https://www.npmjs.com/package/node-font-face-generator
- Repository: https://github.com/shane-tomlinson/node-font-face-generator
- Issues: https://github.com/shane-tomlinson/node-font-face-generator/issues
- npm.io page: https://npm.io/package/node-font-face-generator

## Dependencies (2)

- [ejs](https://npm.io/package/ejs.md) 1.0.0
- [node-uap](https://npm.io/package/node-uap.md) 0.0.3

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 0.1.9 (latest) — 2017-04-18
- 0.1.8 — 2017-04-17
- 0.1.7 — 2017-04-17
- 0.1.6 — 2016-06-15
- 0.1.5 — 2014-07-11
- 0.1.3 — 2014-03-21
- 0.1.2 — 2013-12-19
- 0.1.1 — 2013-06-09
- 0.1.0-dev1 — 2013-03-27
- 0.0.10 — 2013-02-21
- 0.0.9 — 2013-01-27
- 0.0.8 — 2013-01-22
- 0.0.7 — 2013-01-22
- 0.0.6 — 2012-10-12
- 0.0.5 — 2012-10-06
- … 4 more at https://npm.io/package/node-font-face-generator/versions

## README

# node-font-face-generator
A node module to generate locale/browser dependent @font-face CSS declarations.

## Usage
1. Include node-font-face-generator in a node module.
```
const css_generator = require("node-font-face-generator");
```

2. Set up your configuration.
Call `.setup` with configuration.

Possible options:
  * `fonts`
  * `localeToUrlKeys`
  * `urlModifier`
  * `host`

`fonts` is an Object that holds a dictionary of fonts.
```
font_config = {
  "OpenSansRegular": {
    "fontFamily": "Open Sans",
    "fontStyle": "normal",
    "fontWeight": "400",
    "formats": [ {
        "type": "local",
        "url": "Open Sans"            // TrueType name (for most OSs)
      }, {
        "type": "local",
        "url": "Open Sans-Regular"    // PostScript name (for OSX)
      }, {
        "type": "embedded-opentype",
        "url": "/fonts/OpenSans-Regular.eot"
      }, {
        "type": "woff",
        "url": {
          "latin": "/fonts/OpenSans-Regular-latin.woff",
          "cyrillic": "/fonts/OpenSans-Regular-cyrillic.woff",
          "default": "/fonts/OpenSans-Regular-default.woff",
          "chinese": "/fonts/OpenSans-Regular-chinese.woff",
        }
      }, {
        "type": "truetype",
        "url": {
          "latin": "/fonts/OpenSans-Regular-latin.ttf",
          "default": "/fonts/OpenSans-Regular-default.ttf"
        }
      }, {
        "type": "svg",
        "url": {
          "latin": "/fonts/OpenSans-Regular-latin.svg",
          "default": "/fonts/OpenSans-Regular-default.svg"
        },
        "id": "opensans-regular"
      } ],
    // font specific locale to URL keys. Locales defined here override
    // the generic localeToUrlKeys passed in as configuration to
    // .setup.
    "localeToUrlKeys": {
      "cz": "chinese"
    }
  }
};
```

A font have multiple, locale specific URLs. For example, Latin based locales can be specified under the `latin` url, Russian under `cyrillic`, and Greek under `greek`. If multiple urls are defined, the fallback locale `default` *must* be defined.

`localeToUrlKeys` is an optional object that holds a dictionary of locales to urls. localeToUrlKeys kicks in if a locale cannot be directly found in the url list specified for a font. For example:

```
localeToUrlKeys = {
  "en":    "english",   // will match for en, en-US, en-UK, en-CA, ...
  "es":    "spanish",   // will match for es, es-MX, en-AR, en-*
  "fr"     "french",
  "ru":    "russian",
  "ro":    "romanian",
  "bg":    "bulgarian",
  "jp":    "japanese"
};
```

`localeToUrlKeys` may be defined generically for all fonts via the `setup` function, or as an alternative, for each individual font. The rules for how a locale matches to a URL are:

* first, look in the list of URLs specified for a font to see if the locale is available.
* next, look in the list of URLs specified for a font to see if the baseLocale is available.
* next, look in the font specific localeToUrlKeys to see if the locale is specified.
* next, look in the font specific localeToUrlKeys to see if the baseLocale is specified.
* next, look in the generic localeToUrlKeys to see if the locale is specified.
* next, look in the generic localeToUrlKeys to see if the baseLocale is specified.
* next, look in DefaultUrlKeys to see if the locale is specified.
* next, look in DefaultUrlKeys to see if the baseLocale is specified.
* finally, fall back to default.

`DefaultUrlKeys` are a base set of localeToUrlKeys that are compatible with Google Font Directory's `subset.pl` utility. The list is found in `lib/locale_to_url_keys.js`

`urlModifier` is an optional function that is called to modify each URL. This is useful for caching/cache busting. Function must return a string.

`host` is an optional string used to specify a host where fonts are located. Useful if fonts are located on a CDN.

3. Call the `setup` function with the configuration objects.
```
css_generator.setup({
  fonts: font_config,
  localeToUrlKeys: localeToUrlKeys
});
```

4. When CSS for a custom font-face is needed, call `get_font_css` with the
   configuration and a callback. The callback follows node convention and will
   be called with two parameters when complete. The first parameter is any
   error that is thrown (or null), the second is the CSS (or null).
```
var css = css_generator.get_font_css({
  ua: getUserAgent(),
  locale: getUsersLocale(),
  fonts: ["OpenSansRegular"]
}, function(err, css) {
  if (err) {
    // handle the error
    ...
  }
  else if (css) {
    // do something with the CSS
  }
  else {
    // this should never ever happen
  }
});
```

5. It is possible to generate one @font-face with declarations for all
   browsers using `ua: 'all'`. This is useful to create CSS for inclusion
   in a larger CSS file as part of a build script.
```
var css = css_generator.get_font_css({
  ua: 'all',
  locale: getUsersLocale(),
  fonts: ["OpenSansRegular"]
}, function(err, css) {
  if (err) {
    // handle the error
    ...
  }
  else if (css) {
    // This will be the css with fonts declared for all browsers.
  }
  else {
    // this should never ever happen
  }
});
```

6. Do what you will with the CSS. Write it out to a .CSS file in a build script or handle it in an HTTP request.

## Author:
* Shane Tomlinson
* shane@shanetomlinson.com
* stomlinson@mozilla.com
* set117@yahoo.com
* https://shanetomlinson.com
* http://github.com/shane-tomlinson
* @shane_tomlinson

## Getting involved:
I am happy to review submissions!

## License:
This software is available under version 2.0 of the MPL:

  https://www.mozilla.org/MPL/

---
_Source: https://npm.io/package/node-font-face-generator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._