Roads module

Describe road behavior without styling raw layers

roads() controls which roads appear and how strongly the network is presented. The active theme owns every color, so the same road behavior works across light, dark, and branded maps.

tileflow.config.ts

import { defineTileflow, labels, osm, roads } from "@tileflow/core";
 
export default defineTileflow({
  themes: {
    light: {
      colors: {
        road: "#ffffff",
        roadMajor: "#ffffff",
        roadCasing: "#e3e3e3",
      },
      modules: {
        roads: {
          path: "#eeeeee",
          rail: "#aaaaaa",
          ferry: "#82c8ed",
        },
      },
    },
  },
  maps: {
    madrid: {
      basemap: osm(),
      theme: "light",
      modules: [
        roads({
          preset: "navigation",
          detail: "streets",
          hierarchy: "strong",
          weight: "regular",
          casing: "strong",
          extras: {
            paths: false,
            rail: false,
            ferry: false,
          },
        }),
        labels({ roads: "minimal" }),
      ],
    },
  },
});

Presets

Start with a named visual intent

Presets are complete recipes, not hidden renderer switches. They only affect road behavior and produce the same intent on the OSM Bright and generated renderers.

minimaldetail: streets · hierarchy: subtle · weight: thin · casing: subtle · paths, rail, and ferry: off.standarddetail: streets · hierarchy: clear · weight: regular · casing: subtle · paths, rail, and ferry: on.navigationdetail: streets · hierarchy: strong · weight: regular · casing: strong · paths, rail, and ferry: off.detaileddetail: all · hierarchy: clear · weight: regular · casing: strong · paths, rail, and ferry: on.

Controls

Override only the decision you care about

Explicit options override the selected preset. Road labels remain in labels({ roads: ... }) so line styling and text density have one owner each.

detailnone hides roads; major keeps the main network; streets adds local roads; all shows them earlier.hierarchysubtle, clear, or strong controls the visual difference between major and minor roads.weightthin, regular, or bold scales road widths without changing theme colors.casingnone, subtle, or strong controls road outlines.extrasIndependently enables paths, rail, and ferry layers.

Theme colors

Appearance stays in the theme

Use road, roadMajor, and roadCasing for the common palette. Use theme.modules.roads for motorway, trunk, primary, secondary, minor, path, rail, ferry, bridge, and tunnel colors. The module has no color fields.

Precedence

Explicit options win over the preset

This keeps a preset useful without making it a black box. The example starts minimal, increases every road width, and restores rail while preserving the remaining minimal defaults.

roads() override

roads({
  preset: "minimal",
  weight: "bold",
  extras: {
    rail: true,
  },
})

Migration

Old configs remain valid during the alpha

preset: "modern" maps to standard. Legacy density values map to hierarchy: clean becomes subtle, balanced becomes clear, and dense becomes strong. Prefer the new names in new configs.