{"id":14514,"library":"css-font-parser","title":"CSS Font Value Parser","description":"css-font-parser is a lightweight JavaScript utility designed to accurately parse CSS `font` shorthand and `font-family` property values. It extracts structured data such as font size, line height, and a list of font families from a given CSS string. The package is currently at version 2.0.1, with its last publication approximately a year ago. Its release cadence is driven by necessary feature enhancements or bug fixes rather than strict timeframes, reflecting its focused scope. The library's primary differentiation lies in its simplicity and direct focus on parsing these specific CSS properties, providing a programmatic way to deconstruct complex font declarations without the overhead of a full CSS parser. It is particularly useful for tools that need to analyze or manipulate font styles based on their CSS declarations.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/bramstein/css-font-parser","tags":["javascript","css","font","family","parser"],"install":[{"cmd":"npm install css-font-parser","lang":"bash","label":"npm"},{"cmd":"yarn add css-font-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add css-font-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { parseFont } = require('css-font-parser');","symbol":"parseFont","correct":"import { parseFont } from 'css-font-parser';"},{"note":"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.","wrong":"const parseFontFamily = require('css-font-parser').parseFontFamily;","symbol":"parseFontFamily","correct":"import { parseFontFamily } from 'css-font-parser';"},{"note":"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`.","symbol":"FontDeclaration","correct":"import type { FontDeclaration, FontFamily } from 'css-font-parser';"}],"quickstart":{"code":"import { parseFont, parseFontFamily } from 'css-font-parser';\n\n// Example 1: Parsing a basic font shorthand value\nconst parsedFont1 = parseFont('15px sans-serif');\nconsole.log('Parsed Font 1:', parsedFont1);\n/* Expected output:\n{\n  'font-family': ['sans-serif'],\n  'font-size': '15px'\n}\n*/\n\n// Example 2: Parsing a more complex font shorthand with line-height and multiple font families\nconst parsedFont2 = parseFont('15px/18px \"Neue Helvetica\", Helvetica, sans-serif');\nconsole.log('Parsed Font 2:', parsedFont2);\n/* Expected output:\n{\n  'font-family': ['Neue Helvetica', 'Helvetica', 'sans-serif'],\n  'font-size': '15px',\n  'line-height': '18px'\n}\n*/\n\n// Example 3: Parsing only a font-family string\nconst parsedFontFamily = parseFontFamily('\"Neue Helvetica\", Helvetica, system-ui, sans-serif');\nconsole.log('Parsed Font Family:', parsedFontFamily);\n/* Expected output:\n['Neue Helvetica', 'Helvetica', 'system-ui', 'sans-serif']\n*/\n\n// Example with potential error handling (library's error behavior not explicitly defined, so demonstrating usage)\ntry {\n  const invalidFont = parseFont('invalid-font-value');\n  console.log('Parsed Invalid Font (may be incomplete or throw):', invalidFont);\n} catch (e) {\n  console.error('Error parsing invalid font:', e.message);\n}\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: __WEBPACK_IMPORTED_MODULE_0__.parseFont is not a function"},{"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 */ }`.","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.","error":"Cannot read properties of undefined (reading 'font-size') or similar property access error on parser output."}],"ecosystem":"npm"}