Install Package

Install dependency

The @mapvx/web-js package is available on the public npm registry. No authentication token is required to install it.

npm install @mapvx/web-js

Or with other package managers:

# pnpm
pnpm add @mapvx/web-js
 
# yarn
yarn add @mapvx/web-js

Module Formats

The SDK is published in multiple formats to support different environments:

Using with ESM (recommended)

import { initializeSDK } from "@mapvx/web-js"

Using with CommonJS

const { initializeSDK } = require("@mapvx/web-js")

Using via CDN / Script Tag

<link rel="stylesheet" href="https://unpkg.com/@mapvx/web-js/dist/umd/styles.css" />
<script src="https://unpkg.com/@mapvx/web-js/dist/umd/index.js"></script>
<script>
  const sdk = MapVX.initializeSDK("your-api-key")
</script>

The UMD build already includes the MapLibre JavaScript runtime. You only need the SDK stylesheet in addition to index.js.

Map worker and Content-Security-Policy

MapLibre renders tiles on a web worker. The SDK carries that worker inside its own bundle and registers it as a blob: URL when your first map is created, so there is nothing to copy, host or configure — whatever bundler you use, and whatever path your app is served from.

One case needs action: a Content-Security-Policy that does not allow blob: workers. The symptom is a map that stays empty while the browser console shows:

Creating a worker from 'blob:https://your-host/…' violates the following
Content Security Policy directive: "worker-src 'self'"

Nothing is thrown and no SDK error event fires, so that console message is the only signal. Either add worker-src blob: (or child-src blob:) to your policy, or host the worker yourself:

import { setMapLibreWorkerUrl, initializeSDK } from "@mapvx/web-js"
 
// Before creating any map.
setMapLibreWorkerUrl("/assets/maplibre-gl-worker.mjs")
 
const sdk = initializeSDK("your-api-key")

Copy both maplibre-gl-worker.mjs and maplibre-gl-shared.mjs out of maplibre-gl/dist into the same served directory — the worker imports the shared file at runtime. Run npm ls maplibre-gl to see which version the SDK resolved; the files must come from that one. The SDK leaves your URL alone once you set one.

The URL must be same-origin. Serving the worker from a CDN does not help: MapLibre wraps any worker URL it considers cross-origin in a generated blob: worker that imports it, so it runs into the same policy.

API Key for SDK use

After installing the dependency, you need an API Key provided by the MapVX team to enable SDK features.

This API Key is also used for billing purposes, tracking the usage of the various available endpoints.

You can then utilize it when calling the initializeSDK function as follows:

const sdk = initializeSDK("<YOUR-API-KEY>")

CSS Styles Loading

Automatic Loading (Default)

From version 2.22.0+, you can optionally load CSS styles automatically using the loadStyles() function:

import { initializeSDK, loadStyles } from "@mapvx/web-js"
 
// Load default styles automatically
loadStyles()
 
const sdk = initializeSDK("your-api-key", {
  lang: "en",
})

Manual CSS Import

For more control over styling, you can manually include the CSS file in your HTML:

<link rel="stylesheet" href="./node_modules/@mapvx/web-js/dist/umd/styles.css" />

Or import it directly in your bundler:

import "@mapvx/web-js/styles.css"

Custom Styles

The CSS is now separated from the JavaScript bundle, making it easier to:

• Override specific styles in your own CSS
• Load styles conditionally
• Implement custom themes
• Control when styles are applied

Note: The SDK no longer automatically includes CSS styles by default. You must either call loadStyles() or manually include the CSS file.

Cache Configuration

The SDK includes a configurable caching system that can improve performance and enable offline capabilities. You can configure cache behavior when initializing the SDK.

Basic Cache Configuration

import { initializeSDK } from "@mapvx/web-js"
 
const sdk = initializeSDK("your-api-key", {
  lang: "en",
  cache: {
    persistent: true, // Enable localStorage persistence
  },
})

Advanced Cache Configuration

For more control over caching behavior, you can customize limits and TTL (time-to-live) per cache type:

import { initializeSDK } from "@mapvx/web-js"
 
const sdk = initializeSDK("your-api-key", {
  lang: "en",
  cache: {
    persistent: true, // Enable localStorage persistence
    maxStorageBytes: 5 * 1024 * 1024, // 5MB limit for localStorage
    configs: {
      places: {
        maxItems: 1000, // Maximum cached places
        ttlMs: 60 * 60 * 1000, // 1 hour TTL
      },
      routes: {
        maxItems: 200, // Maximum cached routes
        ttlMs: 10 * 60 * 1000, // 10 minutes TTL
      },
      configurations: {
        maxItems: 20,
        ttlMs: 2 * 60 * 60 * 1000, // 2 hours TTL
      },
    },
  },
})

Cache Types

The SDK supports the following cache types, each with configurable maxItems and ttlMs:

Cache Configuration Options

Clearing Route Cache

To clear cached routes (useful when route data may have changed):

// Clear all cached routes
sdk.cleanRoutesCache()

Note: When persistent is enabled, cached data survives page reloads, which is especially useful for kiosk/totem applications or improving load times for returning users.