{"id":11267,"library":"mapbox-to-css-font","title":"Mapbox/MapLibre to CSS Font Utility","description":"mapbox-to-css-font is a focused JavaScript/TypeScript utility designed to convert Mapbox GL Style font definitions, whether single font names or complex fontstacks, into a CSS-compatible `font` shorthand string. The package is currently at version 3.2.0 and is actively maintained, with recent minor releases addressing bug fixes and dependency updates. Its primary function involves parsing Mapbox-specific font declarations and generating a standard CSS font property string, handling details like font size and line height. A key differentiating feature is its intelligent font replacement mechanism, which substitutes common Mapbox/MapLibre fonts (e.g., \"Arial Unicode MS\", \"DIN Pro\") with widely available system fonts or open-source alternatives like Arial or Barlow, ensuring visual consistency when the original fonts are not present. It also correctly extracts style and weight from the primary font within a fontstack and applies it consistently.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"git://github.com/openlayers/mapbox-to-css-font","tags":["javascript","mapbox","maplibre","font","typescript"],"install":[{"cmd":"npm install mapbox-to-css-font","lang":"bash","label":"npm"},{"cmd":"yarn add mapbox-to-css-font","lang":"bash","label":"yarn"},{"cmd":"pnpm add mapbox-to-css-font","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package transitioned to ES modules exclusively in v3.0.0. CommonJS `require()` is no longer supported.","wrong":"const parseFont = require('mapbox-to-css-font');","symbol":"parseFont","correct":"import parseFont from 'mapbox-to-css-font';"},{"note":"While `parseFont` is a default export, if your TypeScript configuration requires explicit type imports, this pattern ensures correctness. However, it's typically used as a runtime value.","symbol":"parseFont","correct":"import type { parseFont } from 'mapbox-to-css-font';"}],"quickstart":{"code":"import parseFont from 'mapbox-to-css-font';\n\n// Example 1: Single font name\nconst cssFont1 = parseFont('Open Sans Regular', 16, 1.2);\nconsole.log(`Single font: ${cssFont1}`);\n// Expected: 'normal 400 16px/1.2 \"Open Sans\"'\n\n// Example 2: Fontstack with Mapbox-specific replacement\nconst cssFont2 = parseFont(['DIN Pro Medium', 'Arial Unicode MS Regular'], 18);\nconsole.log(`Fontstack (DIN Pro): ${cssFont2}`);\n// Expected: 'normal 500 18px \"Barlow\", \"Arial\"'\n\n// Example 3: Fontstack without line height\nconst cssFont3 = parseFont(['Roboto Bold', 'sans-serif'], 20);\nconsole.log(`Fontstack (Roboto Bold): ${cssFont3}`);\n// Expected: 'normal 700 20px \"Roboto\", sans-serif'","lang":"typescript","description":"Demonstrates converting single Mapbox font names and fontstacks into CSS `font` properties, including how the utility handles font replacement and style extraction."},"warnings":[{"fix":"Update your project to use ES module `import` syntax. If you are using Node.js, ensure your package.json has `\"type\": \"module\"` or use `.mjs` file extensions.","message":"Version 3.0.0 introduced a significant breaking change by migrating the package to be ES modules (ESM) only. CommonJS modules are no longer provided, meaning `require()` statements will fail.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review any code that explicitly checks for 'normal' font weight; consider adjusting expectations to '400' or handling both if backward compatibility is needed.","message":"In version 2.4.0, the default font weight for parsed fonts was changed from `normal` to `400`. While `normal` is equivalent to `400` in CSS, this change might subtly affect strict CSS comparisons or workflows expecting the exact `normal` keyword.","severity":"breaking","affected_versions":">=2.4.0 <3.0.0"},{"fix":"Upgrade to version 3.0.3 or later to ensure correct module resolution.","message":"Early versions of v3 (specifically v3.0.0 through v3.0.2) might have experienced issues with main entry point resolution, leading to a `DEP0151` warning or similar module loading failures in some environments. This was fixed in v3.0.3.","severity":"gotcha","affected_versions":">=3.0.0 <3.0.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const parseFont = require('mapbox-to-css-font');` to `import parseFont from 'mapbox-to-css-font';`. Ensure your project is configured for ES modules (e.g., `\"type\": \"module\"` in package.json for Node.js).","cause":"Attempting to use `require()` to import `mapbox-to-css-font` in a CommonJS context when the package is now ESM-only.","error":"ERR_REQUIRE_ESM"},{"fix":"Use a default import: `import parseFont from 'mapbox-to-css-font';` instead of `import { parseFont } from 'mapbox-to-css-font';`.","cause":"Incorrectly trying to import `parseFont` as a named export when it is a default export.","error":"SyntaxError: Named export 'parseFont' not found. The requested module 'mapbox-to-css-font' does not provide an export named 'parseFont'"}],"ecosystem":"npm"}