Frequently Asked Questions

Here you can find answers to the most common questions about use of our SDK.

How can I start using the SDK?

If you want to start using the SDK, you need to contact MapVX in order to get the API key, then follow the instructions on the Installing page

Which browsers My Maps JS SDK supports?

My Maps JS SDK works on all browsers that support WebGL. This includes the most popular browsers, such as:

• Google Chrome 9+
• Firefox 4+
• Safari 5.1+
• Opera 12+
• Microsoft Edge build 10240+

How to resolve npm install error: Package doesn't exist?

The @mapvx/web-js package is public and does not require an npm token. If you encounter this error:

1. Check that you have the correct package name: @mapvx/web-js

2. Verify your npm registry is set to the default:

   npm config get registry
   # Should be: https://registry.npmjs.org/

3. Try clearing the npm cache:

npm cache clean --force
npm install

If that doesn’t work, you can try either of the following commands:

# Reinstall with legacy peer dependencies
npm install --legacy-peer-deps
 
# Reinstall forcefully (use with caution)
npm install --force

Navigation controls are missing on map generation, what can i do?

Make sure you are loading the SDK styles. You can do this programmatically:

import { loadStyles } from "@mapvx/web-js"
 
loadStyles()

Or by including the stylesheet in your HTML:

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

How can I custom the icon of a marker?

If you want to customize the icon of a marker, you need to provide a reference in the icon property when you are creating the marker:

const marker: MarkerConfig = {
    coordinate: {lat: -33.418835, lng: -70.642388},
    icon: "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png",
}

Troubleshooting

Error: “CSS not loading” or “Map styles missing”

From version 2.22.0+, CSS styles are no longer automatically included. You have several options:

Option 1: Use loadStyles() function

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

Option 2: Manual CSS import in HTML

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

Option 3: Custom CSS loading

function loadCustomStyles(path) {
  const link = document.createElement("link")
  link.rel = "stylesheet"
  link.href = path
  link.setAttribute("data-mapvx-styles", "true")
  document.head.appendChild(link)
}
 
loadCustomStyles("./assets/my-custom-styles.css")

Benefits of separate CSS loading

• Better performance: Load styles only when needed
• Easy customization: Override styles without conflicts
• Bundle control: Manage your application’s CSS loading strategy
• Theming support: Implement multiple themes easily

Error: “Container not found”

• Make sure the map container element exists in the DOM before initializing the map
• In React, use useEffect or useLayoutEffect
• In Angular, use ngOnInit or ngAfterViewInit
• In Vue, use onMounted
• Check that the container ID matches exactly

Performance Issues

• Use lazy loading for the SDK if you don’t need it immediately
• Implement proper cleanup on component unmount to avoid memory leaks
• Avoid creating multiple SDK instances
• Use removeAllMarkers() when clearing large numbers of markers

Map not displaying correctly

• Verify your API key is valid and has proper permissions
• Check browser console for any error messages
• Ensure the map container has a defined width and height
• Make sure you’re calling operations after the map is ready (use waitForMapReady())

Network/Loading Issues

• Check your internet connection
• Verify the institution ID and parent place ID are correct
• Some features require specific permissions - contact MapVX support
• Use proper error handling with try/catch blocks

Caching

How do I enable persistent caching?

Enable persistent caching by setting the persistent option in the cache configuration when initializing the SDK:

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

When persistent caching is enabled, data survives page reloads, improving performance for returning users.

How do I configure cache limits?

You can customize cache limits and TTL (time-to-live) per cache type:

const sdk = initializeSDK("your-api-key", {
  lang: "en",
  cache: {
    persistent: true,
    maxStorageBytes: 10 * 1024 * 1024, // 10MB limit
    configs: {
      places: {
        maxItems: 1000, // Maximum number of cached items
        ttlMs: 60 * 60 * 1000, // 1 hour TTL
      },
      routes: {
        maxItems: 200,
        ttlMs: 10 * 60 * 1000, // 10 minutes TTL
      },
    },
  },
})

Available cache types: places, subPlaces, routes, accessibleRoutes, configurations, categories, vehicles, stops.

How do I clear the cache?

To clear the routes cache programmatically:

// Clear cached routes (normal and accessible)
sdk.cleanRoutesCache()

To clear all persistent cache data from localStorage, you can manually remove the SDK’s localStorage keys:

// Clear all MapVX SDK cache from localStorage
const keysToRemove = [
  "lz_places",
  "lz_routes",
  "lz_accessible_routes",
  "lz_configurations",
  "lz_categories",
  "lz_vehicles",
  "lz_stops",
  "lz_subplaces",
]
 
keysToRemove.forEach((key) => localStorage.removeItem(key))

What are the default cache settings?

The default maximum storage size for persistent cache is 5MB.