{"id":25058,"library":"carto","title":"CartoCSS","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/mapbox/carto","tags":["javascript","mapnik","maps","css","stylesheets"],"install":[{"cmd":"npm install carto","lang":"bash","label":"npm"},{"cmd":"yarn add carto","lang":"bash","label":"yarn"},{"cmd":"pnpm add carto","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides Mapnik symbolizers and defaults for compilation","package":"mapnik-reference","optional":false},{"reason":"Resolves external resources (URLs, local files) and projections","package":"millstone","optional":true}],"imports":[{"note":"ESM-only since v1.0","wrong":"const render = require('carto')","symbol":"render","correct":"import { render } from 'carto'"},{"note":"Default export is the Carto class","wrong":"const Carto = require('carto').Carto","symbol":"Carto","correct":"import Carto from 'carto'"},{"note":"MSS is a named export, not default","wrong":"import MSS from 'carto'; new MSS()","symbol":"MSS","correct":"import { MSS } from 'carto'"}],"quickstart":{"code":"import { render } from 'carto';\nimport fs from 'fs';\n\nconst mml = {\n  layers: [{\n    name: 'mylayer',\n    geometry: 'polygon',\n    Datasource: {\n      type: 'csv',\n      file: './data.shp'\n    }\n  }],\n  Stylesheet: ['style.mss']\n};\n\nrender(mml, (err, output) => {\n  if (err) throw err;\n  fs.writeFileSync('mapnik.xml', output);\n});","lang":"typescript","description":"Compiles a CartoCSS project from an MML object into Mapnik XML using the render function."},"warnings":[{"fix":"Use import statements or update bundler to handle ESM.","message":"CartoCSS v1.0 switches from CommonJS to ESM-only. require() calls will fail.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Remove --nosymlink usage; symlink behavior is now default.","message":"The --nosymlink flag is deprecated in favor of using absolute paths by default.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Run 'npm install -g millstone' to enable resource localization.","message":"Millstone must be installed separately for --localize to work. Installing carto alone does not include it.","severity":"gotcha","affected_versions":">=0.18.0"},{"fix":"Ensure 'Stylesheet' property contains paths to .mss files.","message":"When using the API, passing an MML object must include 'Stylesheet' array; otherwise compilation may fail silently.","severity":"gotcha","affected_versions":">=0.15.0"},{"fix":"Specify output format with -o flag if needed.","message":"Output format changed: 'mapnik' is default, 'json' outputs Mapnik JSON variant. Older versions outputted XML differently.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'npm install carto' in your project directory.","cause":"Carto not installed or module path not found.","error":"Error: Cannot find module 'carto'"},{"fix":"Use import { render } from 'carto' (named export).","cause":"Incorrect import: using default import instead of named export.","error":"TypeError: render is not a function"},{"fix":"Switch to import statements.","cause":"Using require() in ESM-only version (v1.0+).","error":"ReferenceError: require is not defined in ES module scope, you can use import instead"},{"fix":"Run 'npm install -g millstone' or install locally.","cause":"Millstone not installed when using --localize.","error":"Error: Please install millstone to use the --localize option"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}