CSS Font Value Parser

Common errors

• TypeError: __WEBPACK_IMPORTED_MODULE_0__.parseFont is not a function

  cause This error typically occurs in a bundled environment (like Webpack or Vite) when attempting to use a CommonJS `require` for an ESM-only library, or when the bundler cannot correctly resolve the named exports of an ESM module.
  fix Ensure you are using ESM named imports: `import { parseFont } from 'css-font-parser';`. Verify your bundler configuration supports ESM and is correctly transpiling or resolving modules. If running in Node.js, confirm your `package.json` has `"type": "module"` or use a `.mjs` file extension.

• Cannot read properties of undefined (reading 'font-size') or similar property access error on parser output.

  cause This error occurs when attempting to access a property (like `font-size`) on the object returned by `parseFont`, but the property is missing because the input CSS string was invalid or did not contain that specific font component.
  fix Always check for the existence of properties on the parsed object before accessing them, especially when dealing with potentially malformed user input. For example, `if (parsedFont['font-size']) { /* use font-size */ }`.

Warnings

• breaking Version 2.0.0 of `css-font-parser` likely transitioned to an ECMAScript Modules (ESM) primary distribution, dropping direct CommonJS (CJS) compatibility without explicit default exports or wrapper files. This change is typical for modern JavaScript libraries to align with browser and Node.js standards.
  Fix: Update your import statements to use ESM syntax: `import { parseFont, parseFontFamily } from 'css-font-parser';`. If using Node.js, ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) or use a bundler that handles ESM-to-CJS transpilation.
• gotcha The library is specifically designed to parse CSS `font` shorthand and `font-family` properties. It does not provide a full CSS parsing solution. Attempting to pass unrelated CSS properties or complex stylesheets will lead to incomplete or incorrect results.
  Fix: Ensure that the input strings provided to `parseFont` and `parseFontFamily` strictly adhere to valid CSS `font` or `font-family` syntax, respectively. For broader CSS parsing, consider a more comprehensive CSS parser library.
• gotcha The parser might be strict with malformed or invalid CSS font syntax. Depending on the exact malformation, it might return an empty or partial result, or throw a parsing error. Its error reporting for invalid input may not be highly descriptive.
  Fix: Validate input CSS strings before passing them to the parser where possible. Wrap parsing calls in `try...catch` blocks to gracefully handle potential errors and provide user-friendly feedback for invalid CSS input. Inspect the output object for missing properties to detect incomplete parses.

Install

• npm install css-font-parser npm
• yarn add css-font-parser yarn
• pnpm add css-font-parser pnpm

Imports

• parseFont
  wrong:

  const { parseFont } = require('css-font-parser');

  correct:

  import { parseFont } from 'css-font-parser';

  The library primarily offers named exports and is designed for ESM consumption since v2. Using CommonJS `require` might lead to unexpected behavior or `undefined` exports without explicit transpilation or bundler configuration.
• parseFontFamily
  wrong:

  const parseFontFamily = require('css-font-parser').parseFontFamily;

  correct:

  import { parseFontFamily } from 'css-font-parser';

  Ensure you are using named imports for `parseFontFamily`. Attempting to destructure it from a CommonJS `require` call in an ESM context, or vice-versa, can fail.
• FontDeclaration

  import type { FontDeclaration, FontFamily } from 'css-font-parser';

  The library provides TypeScript definitions for its parsed output types, such as `FontDeclaration` for the object returned by `parseFont` and `FontFamily` for the array returned by `parseFontFamily`.

Quickstart

This quickstart demonstrates how to use `parseFont` and `parseFontFamily` to extract structured data from CSS font strings, including handling complex font declarations and showing basic error handling for malformed input.

import { parseFont, parseFontFamily } from 'css-font-parser';

// Example 1: Parsing a basic font shorthand value
const parsedFont1 = parseFont('15px sans-serif');
console.log('Parsed Font 1:', parsedFont1);
/* Expected output:
{
  'font-family': ['sans-serif'],
  'font-size': '15px'
}
*/

// Example 2: Parsing a more complex font shorthand with line-height and multiple font families
const parsedFont2 = parseFont('15px/18px "Neue Helvetica", Helvetica, sans-serif');
console.log('Parsed Font 2:', parsedFont2);
/* Expected output:
{
  'font-family': ['Neue Helvetica', 'Helvetica', 'sans-serif'],
  'font-size': '15px',
  'line-height': '18px'
}
*/

// Example 3: Parsing only a font-family string
const parsedFontFamily = parseFontFamily('"Neue Helvetica", Helvetica, system-ui, sans-serif');
console.log('Parsed Font Family:', parsedFontFamily);
/* Expected output:
['Neue Helvetica', 'Helvetica', 'system-ui', 'sans-serif']
*/

// Example with potential error handling (library's error behavior not explicitly defined, so demonstrating usage)
try {
  const invalidFont = parseFont('invalid-font-value');
  console.log('Parsed Invalid Font (may be incomplete or throw):', invalidFont);
} catch (e) {
  console.error('Error parsing invalid font:', e.message);
}