carto

library1.2.0jsnpmunverified

CartoCSS (Carto) is a language and compiler for designing maps, targeting the Mapnik renderer. It compiles CSS-like style rules into Mapnik XML or JSON. Current stable version is 1.2.0 (released with updated dependencies and support for new Mapnik API versions). Maintained by Mapbox, with irregular releases. Key differentiators: CSS-like syntax familiar to web developers, variable support, map data filtering, and compatibility with tools like TileMill, Kosmtik, and Mapbox Studio Classic.

serialization data

npm install carto

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CARTO

carto

serializationjavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

render

✓ import { render } from 'carto'

✗ const render = require('carto')

ESM-only since v1.0

Carto

✓ import Carto from 'carto'

✗ const Carto = require('carto').Carto

Default export is the Carto class

MSS

✓ import { MSS } from 'carto'

✗ import MSS from 'carto'; new MSS()

MSS is a named export, not default

Compiles a CartoCSS project from an MML object into Mapnik XML using the render function.

import { render } from 'carto'; import fs from 'fs'; const mml = { layers: [{ name: 'mylayer', geometry: 'polygon', Datasource: { type: 'csv', file: './data.shp' } }], Stylesheet: ['style.mss'] }; render(mml, (err, output) => { if (err) throw err; fs.writeFileSync('mapnik.xml', output); });

carto --version

Debug

Known issues

breakingCartoCSS v1.0 switches from CommonJS to ESM-only. require() calls will fail.

fix

Use import statements or update bundler to handle ESM.

affects: >=1.0.0

deprecatedThe --nosymlink flag is deprecated in favor of using absolute paths by default.

fix

Remove --nosymlink usage; symlink behavior is now default.

affects: >=1.0.0

gotchaMillstone must be installed separately for --localize to work. Installing carto alone does not include it.

fix

Run 'npm install -g millstone' to enable resource localization.

affects: >=0.18.0

gotchaWhen using the API, passing an MML object must include 'Stylesheet' array; otherwise compilation may fail silently.

fix

Ensure 'Stylesheet' property contains paths to .mss files.

affects: >=0.15.0

breakingOutput format changed: 'mapnik' is default, 'json' outputs Mapnik JSON variant. Older versions outputted XML differently.

fix

Specify output format with -o flag if needed.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'carto'

Carto not installed or module path not found.

fix

Run 'npm install carto' in your project directory.

TypeError: render is not a function

Incorrect import: using default import instead of named export.

fix

Use import { render } from 'carto' (named export).

ReferenceError: require is not defined in ES module scope, you can use import instead

Using require() in ESM-only version (v1.0+).

fix

Switch to import statements.

Error: Please install millstone to use the --localize option

Millstone not installed when using --localize.

fix

Run 'npm install -g millstone' or install locally.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

mapnik-referencerequiredProvides Mapnik symbolizers and defaults for compilation

millstoneoptionalResolves external resources (URLs, local files) and projections

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mapbox/carto ↗

packagehttps://www.npmjs.com/package/carto ↗

homepagehttps://carto.com/ ↗