Mapbox/MapLibre to CSS Font Utility

3.2.0 · active · verified Sun Apr 19

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.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import `mapbox-to-css-font` in a CommonJS context when the package is now ESM-only.

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).
```
SyntaxError: Named export 'parseFont' not found. The requested module 'mapbox-to-css-font' does not provide an export named 'parseFont'
```
cause Incorrectly trying to import `parseFont` as a named export when it is a default export.

fix Use a default import: `import parseFont from 'mapbox-to-css-font';` instead of `import { parseFont } from 'mapbox-to-css-font';`.

Warnings

breaking 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.
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.
breaking 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.
Fix: Review any code that explicitly checks for 'normal' font weight; consider adjusting expectations to '400' or handling both if backward compatibility is needed.
gotcha 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.
Fix: Upgrade to version 3.0.3 or later to ensure correct module resolution.

Install

npm install mapbox-to-css-font npm
yarn add mapbox-to-css-font yarn
pnpm add mapbox-to-css-font pnpm

Imports

parseFont
wrong:
```
const parseFont = require('mapbox-to-css-font');
```
correct:
```
import parseFont from 'mapbox-to-css-font';
```
The package transitioned to ES modules exclusively in v3.0.0. CommonJS `require()` is no longer supported.
parseFont
```
import type { parseFont } from 'mapbox-to-css-font';
```
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.

Quickstart

Demonstrates converting single Mapbox font names and fontstacks into CSS `font` properties, including how the utility handles font replacement and style extraction.

import parseFont from 'mapbox-to-css-font';

// Example 1: Single font name
const cssFont1 = parseFont('Open Sans Regular', 16, 1.2);
console.log(`Single font: ${cssFont1}`);
// Expected: 'normal 400 16px/1.2 "Open Sans"'

// Example 2: Fontstack with Mapbox-specific replacement
const cssFont2 = parseFont(['DIN Pro Medium', 'Arial Unicode MS Regular'], 18);
console.log(`Fontstack (DIN Pro): ${cssFont2}`);
// Expected: 'normal 500 18px "Barlow", "Arial"'

// Example 3: Fontstack without line height
const cssFont3 = parseFont(['Roboto Bold', 'sans-serif'], 20);
console.log(`Fontstack (Roboto Bold): ${cssFont3}`);
// Expected: 'normal 700 20px "Roboto", sans-serif'

view raw JSON →