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
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
- TerrainModule: Hillshade shading and 3D terrain
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. MapLibre stays fully exposed, so its API and plugins cover whatever the modules don't (when to use which).
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.create(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, TerrainModule.
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