Registry / serialization / css-font-face-src

css-font-face-src

library2.1.0jsnpmunverified

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.

serialization

npm install css-font-face-src

github ↗package ↗

INSTALL

IMPORT

SIG · CSS-FONT-FACE-SRC

css-font-face-src

serializationjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'css-font-face-src';

✗ const parser = require('css-font-face-src'); parser.parse(...);

For ESM environments, use named import. CommonJS `require` pattern is also available but less idiomatic in modern projects.

serialize

✓ import { serialize } from 'css-font-face-src';

✗ const parser = require('css-font-face-src'); parser.serialize(...);

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.

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") */

Debug

Known issues

breakingVersion 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.

affects: >=2.0.0

gotchaWhen 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.

affects: >=2.0.0

gotchaPrior 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.

affects: <0.2.2

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'parse')

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[]'.

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[])`.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/cburgmer/css-font-face-src ↗

packagehttps://www.npmjs.com/package/css-font-face-src ↗