Introduction to the Map bundle

Map Architecture

The map bundle of TomTom Maps SDK for JavaScript leverages MapLibre GL JS as a peer dependency and provides seamless integration with TomTom's mapping services and data.

TomTomMap: The Foundation

TomTomMap is your entry point—a lightweight wrapper around MapLibre's Map class that handles initialization, configuration, and lifecycle management. It provides:

• Pre-configured access to TomTom map styles and services
• Unified event handling system for user interactions
• Style management with automatic state preservation
• Direct access to the underlying MapLibre instance when needed

Learn more about TomTomMap →

Modules: Extensible Functionality

Modules are objects that add specialized capabilities to your map. Each module is self-contained and focused on a specific domain:

• BaseMapModule: Control layer groups and base map visibility
• TrafficFlowModule / TrafficIncidentsModule: Real-time traffic visualization
• RoutingModule: Display routes and waypoints
• PlacesModule: Search results and POI visualization
• GeometriesModule: Custom shapes and polygons
• POIsModule: Points of interest filtering and events
• HillshadeModule: Terrain elevation shading

Learn more about Modules →

Why This Architecture?

This separation of concerns provides several benefits:

Tree-shaking: Only bundle the modules you use. A basic map with traffic is significantly smaller than one with full routing and places capabilities.

Composition: Modules work together seamlessly. Multiple instances of the same module type can coexist when needed (e.g., multiple route visualizations).

Flexibility: Start simple with just TomTomMap, then add modules as your requirements grow. Upgrade MapLibre versions independently. Use MapLibre as-is when needed.

Adding Modules

import { TrafficFlowModule, RoutingModule } from '@tomtom-org/maps-sdk/map';

// Add traffic visualization
const trafficFlowModule = await TrafficFlowModule.get(map);

// Add routing capabilities
const routingModule = await RoutingModule.get(map);

Each module follows a consistent .get() pattern for initialization, ensuring they're properly attached to the map and ready to use.

Data Sources

Modules fall into two categories based on their data source:

Built-in Data Modules: Work with existing map data without additional API calls. Typically based on existing vector tiles.

• For example: BaseMapModule, POIsModule, TrafficIncidentsModule, TrafficFlowModule, HillshadeModule.

Service-Driven Modules: Display data from TomTom services or custom GeoJSON. Typically used in combination with TomTom services or your custom data.

• For example: PlacesModule, RoutingModule, GeometriesModule.

This distinction helps you understand what data you'll need and when additional API calls are required.

Next Steps

• TomTomMap Guide: Learn how to initialize and use a TomTom map
• Modules Guide: Learn how the Map Modules work
• Map Styles: Customize the overall map appearance
• User Interaction Events: Handle user interactions