{"id":15582,"library":"css-font-face-src","title":"CSS @font-face src Property Parser","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/cburgmer/css-font-face-src","tags":["javascript","css","parser","value","font","font-face","typescript"],"install":[{"cmd":"npm install css-font-face-src","lang":"bash","label":"npm"},{"cmd":"yarn add css-font-face-src","lang":"bash","label":"yarn"},{"cmd":"pnpm add css-font-face-src","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ESM environments, use named import. CommonJS `require` pattern is also available but less idiomatic in modern projects.","wrong":"const parser = require('css-font-face-src');\nparser.parse(...);","symbol":"parse","correct":"import { parse } from 'css-font-face-src';"},{"note":"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.","wrong":"const parser = require('css-font-face-src');\nparser.serialize(...);","symbol":"serialize","correct":"import { serialize } from 'css-font-face-src';"},{"note":"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.","symbol":"FontFaceSrcItem","correct":"import { FontFaceSrcItem } from 'css-font-face-src';"}],"quickstart":{"code":"import { parse, serialize, FontFaceSrcItem } from 'css-font-face-src';\n\nconst cssSrcString = 'local(\"The Font\"), url(\"font.otf\") format(\"opentype\"), url(\"font.woff\"), local(\"Another Font\"), url(\"font.svg\") tech(\"svg\")';\n\n// Parse the CSS src string into a structured array of objects\nconst parsedItems = parse(cssSrcString);\n\nconsole.log('Parsed items:');\nconsole.log(JSON.stringify(parsedItems, null, 2));\n\n// Modify the parsed items (e.g., add a new font source)\nconst modifiedItems: FontFaceSrcItem[] = [\n  ...parsedItems,\n  { url: 'https://example.com/new-font.ttf', format: 'truetype' }\n];\n\n// Serialize the (potentially modified) object array back to a CSS string\nconst serializedString = serialize(modifiedItems);\n\nconsole.log('\\nModified and serialized string:');\nconsole.log(serializedString);\n\n/* Expected Output:\nParsed items:\n[\n  {\n    \"local\": \"The Font\"\n  },\n  {\n    \"url\": \"font.otf\",\n    \"format\": \"opentype\"\n  },\n  {\n    \"url\": \"font.woff\"\n  },\n  {\n    \"local\": \"Another Font\"\n  },\n  {\n    \"url\": \"font.svg\",\n    \"tech\": \"svg\"\n  }\n]\n\nModified and serialized string:\nlocal(\"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\")\n*/","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Cast your array of font face source objects like `serialize(myArray as FontFaceSrcItem[])` to provide the compiler with the expected type definition.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure you are using version 0.2.2 or higher. Earlier versions may have missing grammar files, causing runtime errors.","message":"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.","severity":"gotcha","affected_versions":"<0.2.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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');`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'parse')"},{"fix":"Explicitly cast the array to `FontFaceSrcItem[]`. For example: `serialize([{ local: 'Font' }] as FontFaceSrcItem[])`.","cause":"This TypeScript error occurs when passing an untyped or insufficiently typed array of objects to the `serialize` function without explicit type assertion.","error":"Argument of type '{ local: string; }[]' is not assignable to parameter of type 'FontFaceSrcItem[]'."}],"ecosystem":"npm"}