Core quickstart

The Core bundle provides essential shared functionality across the entire Maps SDK, including configuration management, common types, and utility functions.

Installing dependencies

The Core bundle is automatically included when you install the Map or Services bundles:

# 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):

• lodash-es (v4) - Utility functions
• @turf/turf (v7) - Geospatial analysis

For more details, see the Project setup guide.

Common configuration

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

TomTomConfig.instance.put({
    apiKey: 'YOUR_API_KEY',
    language: 'en-GB'
});

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.

TomTomConfig.instance.put({
    apiKey: 'YOUR_API_KEY',
    language: 'en-GB',           // Search/routing/map labels language
    commonBaseURL: 'https://api.tomtom.com',  // API base URL
    apiVersion: 1                // Default API version for services
});

For a full reference of every global option — including display units and retry behavior — and how global values combine with per-request options, see the Global configuration guide.

Using with map bundle

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

TomTomConfig.instance.put({
    apiKey: 'YOUR_API_KEY'
});

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

Using with services bundle

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { search } from '@tomtom-org/maps-sdk/services';

TomTomConfig.instance.put({
    apiKey: 'YOUR_API_KEY'
});

const results = await search({
    query: 'restaurants',
    position: [4.9041, 52.3676]
});

Node.js configuration

const { TomTomConfig } = require('@tomtom-org/maps-sdk/core');

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

The Core bundle is automatically included when you install the Map or Services bundles - no separate installation needed.