v-maplibre
Guide

Getting Started

Get started with v-maplibre in your Vue 3 or Nuxt project

Installation

Only two packages are required.@geoql/v-maplibre keeps the install lean — deck.gl, raster, wind, LiDAR, and starfield support are all opt-in. See Optional Packages below.

Install the library and its single peer dependency:

pnpm add @geoql/v-maplibre maplibre-gl

That covers VMap, VMarker, VPopup, all controls (VControl*), and every MapLibre-native layer (VLayerMaplibre*).

Import Styles

Import the required CSS files in your main application file or component:

// main.ts or app.vue
import 'maplibre-gl/dist/maplibre-gl.css';
import '@geoql/v-maplibre/dist/v-maplibre.css';

MapLibre GL v6 Worker

MapLibre GL v6 loads its worker from a URL it builds at runtime, which bundlers cannot see — an app without wiring requests maplibre-gl-worker.mjs next to the app bundle and gets a 404 (#160).

VMap handles it for you: it points MapLibre at a self-contained worker shipped with the library. The reference uses the standard new URL('./maplibre-worker.js', import.meta.url) pattern, which Vite (dev + build) and webpack 5 both emit as an asset. No setup needed.

Prefer a worker built from your own maplibre-gl version? Set it before the first VMap mounts — the library keeps an existing URL:

// plugins/maplibre-worker.client.ts (Nuxt) or main.ts (Vite)
import { setWorkerUrl } from 'maplibre-gl';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';

setWorkerUrl(workerUrl);
The ?worker&url import is Vite-specific. Consumers on other bundlers need no override — the shipped worker covers them.

Basic Usage

Here's a simple example to render a map:

<script setup lang="ts">
  import { VMap } from '@geoql/v-maplibre';
  import 'maplibre-gl/dist/maplibre-gl.css';
  import '@geoql/v-maplibre/dist/v-maplibre.css';

  const mapOptions = {
    style: 'https://demotiles.maplibre.org/style.json',
    center: [-74.5, 40],
    zoom: 9,
  };
</script>

<template>
  <VMap :options="mapOptions" style="height: 500px"></VMap>
</template>

Nuxt Usage

For Nuxt applications, you need to configure the component to only render on the client side:

<script setup lang="ts">
  import { VMap } from '@geoql/v-maplibre';

  const mapOptions = {
    style: 'https://demotiles.maplibre.org/style.json',
    center: [-74.5, 40],
    zoom: 9,
  };
</script>

<template>
  <ClientOnly>
    <VMap :options="mapOptions" style="height: 500px"></VMap>
  </ClientOnly>
</template>

Nuxt Global CSS (Recommended)

Add the styles to your nuxt.config.ts for global availability:

// nuxt.config.ts
export default defineNuxtConfig({
  css: [
    'maplibre-gl/dist/maplibre-gl.css',
    '@geoql/v-maplibre/dist/v-maplibre.css',
  ],
});

Or use a Nuxt plugin:

// plugins/maplibre.client.ts
import 'maplibre-gl/dist/maplibre-gl.css';
import '@geoql/v-maplibre/dist/v-maplibre.css';

export default defineNuxtPlugin(() => {
  // Plugin loaded
});

Optional Packages

Add these only for the layers you actually use. Each row's components stay tree-shaken out of your bundle until you import them:

FeatureComponentsInstall
deck.gl baseVLayerDeckgl, VLayerDeckglScatterplot, VLayerDeckglArc, VLayerDeckglLine, VLayerDeckglPath, VLayerDeckglPolygon, VLayerDeckglSolidPolygon, VLayerDeckglGeojson, VLayerDeckglIcon, VLayerDeckglText, VLayerDeckglColumn, VLayerDeckglBitmap, VLayerDeckglPointCloudpnpm add @deck.gl/core @deck.gl/layers @deck.gl/mapbox
AggregationVLayerDeckglHeatmap, VLayerDeckglHexagon, VLayerDeckglGrid, VLayerDeckglGridCell, VLayerDeckglContour, VLayerDeckglScreenGridpnpm add @deck.gl/aggregation-layers
Geo / tilesVLayerDeckglTrips, VLayerDeckglMVT, VLayerDeckglTile, VLayerDeckglTile3D, VLayerDeckglTerrain, VLayerDeckglH3Hexagon, VLayerDeckglH3Cluster, VLayerDeckglS2, VLayerDeckglGeohash, VLayerDeckglQuadkey, VLayerDeckglGreatCircle, VLayerDeckglWMSpnpm add @deck.gl/geo-layers
3D meshVLayerDeckglSimpleMesh, VLayerDeckglScenegraphpnpm add @deck.gl/mesh-layers
Raster (COG)VLayerCog, VLayerMultiCog, VLayerMosaicpnpm add @developmentseed/deck.gl-geotiff @developmentseed/deck.gl-raster @developmentseed/geotiff @developmentseed/proj
ZarrVLayerZarrpnpm add @developmentseed/deck.gl-zarr zarrita
GeoArrowVLayerDeckglGeoArrowScatterplot, VLayerDeckglGeoArrowPath, VLayerDeckglGeoArrowPolygon, VLayerDeckglGeoArrowSolidPolygon, VLayerDeckglGeoArrowText, VLayerDeckglGeoArrowTripspnpm add @deck.gl/layers apache-arrow (+ @deck.gl/geo-layers for trips)
Wind particlesVLayerWindParticlepnpm add maplibre-gl-wind
LiDARVControlLidarpnpm add maplibre-gl-lidar
StarfieldVLayerStarfieldpnpm add @geoql/maplibre-gl-starfield three

If you import a layer without its peer deps installed, your bundler will report Cannot find module '...' — install the missing package(s) from the row above to resolve it.

Next Steps

Peer Dependencies

Which packages each v-maplibre component requires, and how to install only what you use.

Copyright © 2026