CartoCSS

1.2.0 verified Fri May 01 auth: no javascript

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.

Common errors

error Error: Cannot find module 'carto' ↓

cause Carto not installed or module path not found.

fix

Run 'npm install carto' in your project directory.

error TypeError: render is not a function ↓

cause Incorrect import: using default import instead of named export.

fix

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

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

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

fix

Switch to import statements.

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

cause Millstone not installed when using --localize.

fix

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

Warnings

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

fix Use import statements or update bundler to handle ESM.

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

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

gotcha Millstone 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.

gotcha When 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.

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

fix Specify output format with -o flag if needed.

Install

npm install carto

yarn add carto

pnpm add carto

Imports

render

wrong

const render = require('carto')

correct

import { render } from 'carto'

ESM-only since v1.0

Carto

wrong

const Carto = require('carto').Carto

correct

import Carto from 'carto'

Default export is the Carto class

MSS

wrong

import MSS from 'carto'; new MSS()

correct

import { MSS } from 'carto'

MSS is a named export, not default

Quickstart

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);
});