CSS @font-face src Property Parser

2.1.0 · active · verified Tue Apr 21

css-font-face-src is a focused JavaScript and TypeScript library designed to parse and serialize the `src` property value of CSS `@font-face` rules. It transforms complex CSS `src` strings into an array of structured objects, distinguishing between local font references and remote URLs (with optional format and `tech()` fragments), and can convert these objects back into a valid CSS string. The current stable version is 2.1.0. The package has a moderate release cadence, with significant updates in major versions like v2.0.0 introducing TypeScript support and minor versions adding support for newer CSS specifications (e.g., CSS Fonts Module Level 4 `tech()` fragment in v2.1.0). Its primary differentiator is its dedicated, precise parsing capability for this specific CSS property, providing a reliable programmatic interface for manipulating font declarations.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'parse')
```
cause Attempting to use `parser.parse()` after an ESM `import { parse } from 'css-font-face-src';` or using `require('css-font-face-src').parse` when only `require('css-font-face-src')` was intended to directly provide the `parse` function.

fix If using ESM, ensure you are destructuring named exports: `import { parse, serialize } from 'css-font-face-src';`. If using CommonJS and expecting `parser.parse`, then `const parser = require('css-font-face-src');` is correct. If you incorrectly assumed `require` directly returned `parse`, change to `const { parse } = require('css-font-face-src');`.
```
Argument of type '{ local: string; }[]' is not assignable to parameter of type 'FontFaceSrcItem[]'.
```
cause This TypeScript error occurs when passing an untyped or insufficiently typed array of objects to the `serialize` function without explicit type assertion.

fix Explicitly cast the array to `FontFaceSrcItem[]`. For example: `serialize([{ local: 'Font' }] as FontFaceSrcItem[])`.

Warnings

breaking Version 2.0.0 introduced TypeScript support. While this is largely additive, it might lead to build errors in existing JavaScript projects if type declarations are inadvertently pulled in or if tooling isn't configured for mixed JS/TS. The primary interface for `require` remained the same, but ESM imports are now preferred.
Fix: For TypeScript projects, ensure `tsconfig.json` is set up correctly. For JavaScript projects, ensure bundlers are configured to ignore `.d.ts` files if conflicts arise, or explicitly use CommonJS `require` syntax if experiencing issues with module resolution.
gotcha When using the `serialize` function with TypeScript, it's often necessary to explicitly cast the input array to `FontFaceSrcItem[]` to satisfy type checking, especially if the array is constructed dynamically or partially typed. This is demonstrated in the README examples.
Fix: Cast your array of font face source objects like `serialize(myArray as FontFaceSrcItem[])` to provide the compiler with the expected type definition.
gotcha Prior to version 0.2.2, there were issues with the grammar file not being correctly included in the npm package, leading to errors upon installation or runtime when the parser attempted to load the grammar. This was a publishing bug, not a code bug.
Fix: Ensure you are using version 0.2.2 or higher. Earlier versions may have missing grammar files, causing runtime errors.

Install

npm install css-font-face-src npm
yarn add css-font-face-src yarn
pnpm add css-font-face-src pnpm

Imports

parse
wrong:
```
const parser = require('css-font-face-src');
parser.parse(...);
```
correct:
```
import { parse } from 'css-font-face-src';
```
For ESM environments, use named import. CommonJS `require` pattern is also available but less idiomatic in modern projects.
serialize
wrong:
```
const parser = require('css-font-face-src');
parser.serialize(...);
```
correct:
```
import { serialize } from 'css-font-face-src';
```
Similar to `parse`, use named import for ESM. Direct CommonJS `require` assigns the module to a single variable which then exposes both parse and serialize.
FontFaceSrcItem
```
import { FontFaceSrcItem } from 'css-font-face-src';
```
This is a TypeScript type definition, used for type hinting the input array for `serialize` or the output from `parse`. It's only relevant in TypeScript projects.

Quickstart

This quickstart demonstrates parsing a CSS `src` string, inspecting the resulting object structure, modifying it, and then serializing it back into a CSS string, showcasing both `parse` and `serialize` functions along with TypeScript type usage.

import { parse, serialize, FontFaceSrcItem } from 'css-font-face-src';

const cssSrcString = 'local("The Font"), url("font.otf") format("opentype"), url("font.woff"), local("Another Font"), url("font.svg") tech("svg")';

// Parse the CSS src string into a structured array of objects
const parsedItems = parse(cssSrcString);

console.log('Parsed items:');
console.log(JSON.stringify(parsedItems, null, 2));

// Modify the parsed items (e.g., add a new font source)
const modifiedItems: FontFaceSrcItem[] = [
  ...parsedItems,
  { url: 'https://example.com/new-font.ttf', format: 'truetype' }
];

// Serialize the (potentially modified) object array back to a CSS string
const serializedString = serialize(modifiedItems);

console.log('\nModified and serialized string:');
console.log(serializedString);

/* Expected Output:
Parsed items:
[
  {
    "local": "The Font"
  },
  {
    "url": "font.otf",
    "format": "opentype"
  },
  {
    "url": "font.woff"
  },
  {
    "local": "Another Font"
  },
  {
    "url": "font.svg",
    "tech": "svg"
  }
]

Modified and serialized string:
local("The Font"), url("font.otf") format("opentype"), url("font.woff"), local("Another Font"), url("font.svg") tech("svg"), url("https://example.com/new-font.ttf") format("truetype")
*/

view raw JSON →