Install Package

NPM Key 🔑

First of all, this plugin requires an NPM key provided by My maps team in order to install it. That’s because my-maps-js is a private library, so in order to use it, you need access from the team first.

keep your API key secure, we can delete and create a new one but billing it’s your responsibility.

After obtaining your NPM key, you have two options to configure it:

Option 1: Environment Variable

Add it as an environment variable to your preferred terminal using the following command:

export NPM_TOKEN="<YOUR-API-KEY>"

We encourage you to add it in some .env file or directly on your .bashrc, .bashprofile or .zshrc file.

Option 2: .npmrc File (Recommended)

Create a .npmrc file in your project root or home directory with the following content:

//registry.npmjs.org/:_authToken=<YOUR-API-KEY>
engine-strict=true

This method is more convenient as it automatically handles authentication for the specific scope without affecting other npm operations.

Install dependency

To install the dependency, use this:

npm install @lzdevelopers/my-maps-js --save

This would add the dependency to the package.json file while installing it in your current environment.

API Key for SDK use 🔑

After successfully installing the dependency in your project, you need to add an additional key to enable the features included. This API Key is provided by the Lazarillo team.

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 "@lzdevelopers/my-maps-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/@lzdevelopers/my-maps-js/dist/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 "@lzdevelopers/my-maps-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 "@lzdevelopers/my-maps-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.