Vue 3 Plugin for MapLibre GL JS

Common errors

• Cannot find module 'maplibre-gl' or its corresponding type declarations.

  cause The `maplibre-gl` package, a peer dependency, has not been installed.
  fix Install the `maplibre-gl` package: `npm install maplibre-gl` or `yarn add maplibre-gl`.

• Failed to resolve component: MglMap

  cause The `MglMap` component (or other `Mgl` components) has not been correctly registered globally via `app.use(VueMaplibreGl)` or locally imported and added to the `components` option of a Vue component.
  fix Ensure `import { MglMap } from 'vue-maplibre-gl'` is present and `MglMap` is listed in the `components` object of your Vue component, or perform a global installation using `app.use(VueMaplibreGl)` in your main.js/ts file.

• TypeError: Cannot read properties of undefined (reading 'addControl')

  cause Attempting to use a MapLibre GL JS control (e.g., `NavigationControl`) without initializing it or adding it to an `MglMap` instance correctly. This might also happen if the map instance is not yet ready.
  fix Ensure controls are instantiated and added within the context of an `MglMap` component or its `map` instance, typically after the map `load` event. Use `Mgl*Control` components provided by `vue-maplibre-gl` for easier integration.

Warnings

• gotcha When using the `MglDrawControl` component, additional dependencies from Turf.js are required at runtime. These are not always listed as explicit peer dependencies and must be installed separately to avoid runtime errors related to missing geospatial functions.
  Fix: Manually install required Turf.js modules, e.g., `npm install @turf/turf` or specific `@turf/*` packages if you only need certain functionalities.
• gotcha The Draw Plugin CSS (`vue-maplibre-gl-draw.css`) must be explicitly imported if you intend to use the `MglDrawControl` component. The base `vue-maplibre-gl.css` only provides styles for the core map and controls.
  Fix: Add `@use '~vue-maplibre-gl/dist/vue-maplibre-gl-draw.css';` to your CSS or `import 'vue-maplibre-gl/dist/vue-maplibre-gl-draw.css';` in your JavaScript entry point.
• breaking While not explicitly documented in the `vue-maplibre-gl` changelog, a major version bump in the underlying `maplibre-gl` library (e.g., from v5 to v6) could introduce breaking changes that might affect `vue-maplibre-gl`'s functionality or require updates to map styles or data handling.
  Fix: Always check the `maplibre-gl` changelog for breaking changes when updating. Ensure your `maplibre-gl` peer dependency range is conservative (e.g., `^5.0.0`) to prevent automatic major version upgrades without review. Test your application thoroughly after any `maplibre-gl` update.
• gotcha The library automatically restarts the map on `CONTEXT_LOST_WEBGL` events, which commonly occur on mobile devices when a tab is in the background for an extended period. While a feature to improve reliability, developers should be aware that this can lead to temporary map reinitialization.
  Fix: Account for potential map reloads in your application state management, especially if you store map-related settings (e.g., drawn features, current view) that might need to be reapplied after a context loss and restart.

Install

• npm install vue-maplibre-gl npm
• yarn add vue-maplibre-gl yarn
• pnpm add vue-maplibre-gl pnpm

Imports

• VueMaplibreGl
  wrong:

  const VueMaplibreGl = require('vue-maplibre-gl')

  correct:

  import VueMaplibreGl from 'vue-maplibre-gl'

  This is the default export used for global installation via `app.use(VueMaplibreGl)` in your main Vue application file.
• MglMap
  wrong:

  import MglMap from 'vue-maplibre-gl'

  correct:

  import { MglMap } from 'vue-maplibre-gl'

  Used for importing individual components like `MglMap` when not using the global plugin installation. Other components like `MglNavigationControl` are imported similarly.
• useMap
  wrong:

  VueMaplibreGl.useMap()

  correct:

  import { useMap } from 'vue-maplibre-gl'

  A Vue Composition API hook for accessing registered map instances by a provided key, enabling interaction with multiple maps or global map access.

Quickstart

This quickstart demonstrates how to set up a basic MapLibre GL map within a Vue 3 application, including a navigation control. It shows the necessary imports for CSS and Vue components, and initializes the map with a default style and view.

import { createApp } from 'vue';
import { MglMap, MglNavigationControl } from 'vue-maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import 'vue-maplibre-gl/dist/vue-maplibre-gl.css';
// import 'vue-maplibre-gl/dist/vue-maplibre-gl-draw.css'; // Uncomment if using MglDrawControl

const app = createApp({
  components: {
    MglMap,
    MglNavigationControl,
  },
  data() {
    return {
      mapStyle: 'https://demotiles.maplibre.org/style.json', // Or any other MapLibre GL compatible style URL
      center: [-74.0060, 40.7128], // New York City coordinates
      zoom: 10,
    };
  },
  template: `
    <div style="width: 100%; height: 500px;">
      <mgl-map
        :map-style="mapStyle"
        :center="center"
        :zoom="zoom"
      >
        <mgl-navigation-control position="top-right" />
      </mgl-map>
    </div>
  `,
});

app.mount('#app');