Map quickstart

This guide will help you set up your project and visualize your first TomTom map in just a few minutes. You'll learn the minimal steps needed to install the SDK, configure your API key, and display an interactive map on your webpage.

Prerequisites and setup

Before getting started, ensure you have the following requirements:

1. Node.js and npm/pnpm installed for package management (Node.js 24+, the version the package requires)
2. TomTom API key from my.tomtom.com
3. Modern browser with WebGL support for optimal map rendering performance

Before you ship, decide where this key will live. A key used from the browser can be read by anyone who opens the page. A key used from Node.js cannot. See Where your API key runs for which case you are in and what to do about it, and TomTom's API key management best practices for key restrictions, rotation and monitoring.

Installing dependencies

Follow the complete Project setup guide for detailed installation instructions, or use this quick setup:

# npm or Yarn - automatic peer dependency installation
npm install @tomtom-org/maps-sdk

# pnpm - enable auto-install-peers for easiest setup
echo "auto-install-peers=true" >> .npmrc
pnpm install @tomtom-org/maps-sdk

Peer dependencies (installed automatically with above commands):

• maplibre-gl (v6) - Map rendering engine
• lodash-es (v4) - Utility functions
• @turf/turf (v7) - Geospatial analysis

Basic HTML setup

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>TomTom Map Application</title>
    <style>
        #map { width: 100%; height: 400px; }
    </style>
</head>
<body>
    <div id="map"></div>
    <script type="module" src="./index.ts"></script>
</body>
</html>

Creating your first map

Here's a complete example that demonstrates all the essential concepts for creating a TomTom map with various configuration options:

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { TomTomMap } from '@tomtom-org/maps-sdk/map';

// Configure global SDK settings
TomTomConfig.instance.put({
    apiKey: 'YOUR_API_KEY',
});

const map = new TomTomMap({
    mapLibre: {
        container: 'map'
    }
});

Next step

Now that you have a basic map running, learn about TomTom Maps configuration and usage patterns in our comprehensive TomTom Maps Introduction guide.