Project setup

Install the SDK, set your API key and wire the map into your framework.

Prerequisites and requirements

• A TomTom API key, for map data, services and real-time traffic. Where your API key runs decides how much care it needs before you deploy.
• Node.js 24+ at install time, the package’s engines floor, whether or not you target the browser.
• A browser with WebGL for the Map bundle.
• A bundler such as Vite or Webpack, because the SDK ships as ES modules.
• TypeScript is optional. The type definitions ship with the package.

The Services bundle also runs in Node.js and React Native. The Map bundle runs in the browser, in any framework (React, Vue, Angular or none).

Obtaining your API key

1. Navigate to my.tomtom.com
2. Create an account or sign in to your existing MyTomTom account
3. Go to Products, find Maps SDK for JavaScript in the list and click Start now
4. Click Create new free SDK key
5. Configure key permissions for the APIs you plan to use

AI coding agent skill

Using an AI coding agent? Install the tomtom-maps-sdk-js skill so it writes against the real API. AI coding with the SDK has the install line and the topics it covers.

Installing dependencies

One package, @tomtom-org/maps-sdk, carries all three bundles: /core, /services and /map.

SDK installation

1
npm install @tomtom-org/maps-sdk

Installing peer dependencies

npm (v7+) and Yarn install the peer dependencies with the SDK:

1
npm install @tomtom-org/maps-sdk
2
# or
3
yarn add @tomtom-org/maps-sdk

pnpm installs them once you ask it to:

1
# One-time setup
2
echo "auto-install-peers=true" >> .npmrc
3

4
pnpm add @tomtom-org/maps-sdk

Or install them yourself:

1
pnpm add @tomtom-org/maps-sdk @turf/turf culori lodash-es maplibre-gl zod

Peer dependency requirements by bundle

The package declares all five as peer dependencies, so install all five even when you import one bundle.

Vite projects

MapLibre GL JS v6 runs its web worker from a separate file, maplibre-gl-worker.mjs, which it locates at runtime. Neither the Vite dev server nor vite build emits that file on its own. Without it the map stays blank, and the console logs Worker failed to load.

TomTomMap takes care of it on Vite 8, and in vite build on Vite 7, with no Vite configuration. The SDK hands Vite a worker entry that imports your own maplibre-gl worker. It then registers the URL Vite gives it with MapLibre before creating the map. Your app’s origin serves the worker, with no third-party request, and the worker always matches your MapLibre version. After vite build, dist/assets holds a maplibre-gl-worker-*.js file next to your bundle.

The Vite 7 dev server is the exception. Its pre-bundler moves the SDK into node_modules/.vite/deps/, where the worker entry doesn’t exist. Upgrade to Vite 8, or keep the SDK out of pre-bundling and list its peer dependencies, which Vite then pre-bundles on their own:

1
// vite.config.ts, Vite 7
2
import { defineConfig } from 'vite';
3

4
export default defineConfig({
5
    optimizeDeps: { exclude: ['@tomtom-org/maps-sdk'], include: ['@turf/turf', 'culori/fn', 'lodash-es', 'zod'] },
6
});

TomTomMap leaves MapLibre’s own worker lookup in place when:

• your app already called MapLibre’s setWorkerUrl before creating the map, whose URL it keeps;
• your bundler builds classic workers, as webpack does by default, or builds no worker at all, as with Rollup and esbuild. Set up the worker as the MapLibre documentation describes. With ES module output (output.module and experiments.outputModule), webpack builds a module worker, which TomTomMap registers as it does Vite’s;
• you build with Next.js and Turbopack. It emits neither the worker nor maplibre-gl-shared.mjs, the file the worker imports beside itself. Copy node_modules/maplibre-gl/dist/maplibre-gl-worker.mjs and node_modules/maplibre-gl/dist/maplibre-gl-shared.mjs into one directory under public/, and call MapLibre’s setWorkerUrl with the worker’s public path before you create the map. registerMapLibreWorker: false leaves that same lookup;
• MapLibre loads unbundled, from a CDN or an import map;
• you pass registerMapLibreWorker: false.

1
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
2

3
const map = new TomTomMap({ registerMapLibreWorker: false, mapLibre: { container: 'map' } });

TypeScript support

You don’t need a @types package:

1
import { TomTomConfig, type Language } from '@tomtom-org/maps-sdk/core';
2
import { TomTomMap } from '@tomtom-org/maps-sdk/map';

SDK common configuration

Set your API key once at startup with TomTomConfig. The map and every service call read it from there:

1
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
2

3
TomTomConfig.instance.put({
4
    apiKey: process.env.TOMTOM_API_KEY,
5
    language: 'en-GB',
6
});

• The other options have defaults: language, geopoliticalView, displayUnits, retry, sendUserAgentHeader and commonBaseURL. Global configuration covers each one, and how put merges.
• Language: one of the 39 supported codes, typed as Language, such as en-US, pt-BR, zh-Hans or ngt, the Neutral Ground Truth that shows each place in its local language.
• commonBaseURL: change it only to route requests through a proxy of your own.

Multiple API keys

A service call or a map can override the global key:

1
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
2
import { discoverPlaces } from '@tomtom-org/maps-sdk/services';
3
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
4

5
TomTomConfig.instance.put({ apiKey: process.env.TOMTOM_DEFAULT_API_KEY });
6

7
const results = await discoverPlaces({
8
    query: 'restaurants',
9
    geoBias: { position: [4.9041, 52.3676] },
10
    apiKey: process.env.TOMTOM_PREMIUM_API_KEY, // this call only
11
});
12

13
const map = new TomTomMap({
14
    mapLibre: { container: 'map' },
15
    apiKey: process.env.TOMTOM_MAP_API_KEY, // this map only
16
});

Framework-specific setup

React

1
// src/config/tomtom.js
2
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
3

4
TomTomConfig.instance.put({
5
    apiKey: process.env.REACT_APP_TOMTOM_API_KEY,
6
    language: 'en-US'
7
});
8

9
// src/components/Map.jsx
10
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
11
import { useEffect, useRef } from 'react';
12

13
export function MapComponent() {
14
    const mapRef = useRef();
15

16
    useEffect(() => {
17
        const map = new TomTomMap({
18
            mapLibre: {
19
                container: mapRef.current
20
            }
21
        });
22

23
        return () => map.mapLibreMap.remove();
24
    }, []);
25

26
    return <div ref={mapRef} style={{ width: '100%', height: '400px' }} />;
27
}

Vue

1
// src/plugins/tomtom.js
2
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
3

4
TomTomConfig.instance.put({
5
    apiKey: process.env.VUE_APP_TOMTOM_API_KEY,
6
    language: 'en-US'
7
});
8

9
// src/components/MapComponent.vue
10
<template>
11
    <div ref="mapContainer" class="map-container"></div>
12
</template>
13

14
<script>
15
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
16

17
export default {
18
    mounted() {
19
        this.map = new TomTomMap({
20
            mapLibre: {
21
                container: this.$refs.mapContainer
22
            }
23
        });
24
    },
25
    beforeUnmount() {
26
        this.map?.mapLibreMap.remove();
27
    }
28
};
29
</script>

Node.js

1
// src/config/tomtom.js
2
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
3

4
TomTomConfig.instance.put({
5
    apiKey: process.env.TOMTOM_API_KEY,
6
    language: 'en-US'
7
});
8

9
// src/services/geocoding.js
10
import { geocode } from '@tomtom-org/maps-sdk/services';
11

12
export async function geocodeAddress(query) {
13
    return await geocode({
14
        query
15
    });
16
}

Next steps

• Map quickstart: an interactive map with TomTom data
• Services quickstart: search, geocoding and routing
• Core quickstart: the configuration, types and utilities both share
• Map styles, user events, traffic, POIs and route planning
• The examples gallery, for complete apps to start from