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

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

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.