Guide

Peer Dependencies

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

TL;DR

Only @geoql/v-maplibre and maplibre-gl are required. Everything below is opt-in — install the peer dependencies for the components you actually import.

pnpm add @geoql/v-maplibre maplibre-gl

That alone unlocks the core map, markers, popups, MapLibre native layers, and standard controls. The deck.gl, COG, Wind, LiDAR, and Starfield layers each pull in their own peer packages — install them only when you use those components.

Missing a peer dep at runtime now produces an actionable error that names the package and prints the install command, rather than the opaque Cannot find module '…' you may have seen before.

Core (always required)

Component	Required peer dep(s)	Install command
`VMap`, `VMarker`, `VPopup`	`maplibre-gl`	`pnpm add @geoql/v-maplibre maplibre-gl`

MapLibre native layers + standard controls

All of these ship with @geoql/v-maplibre and need no extra peers beyond maplibre-gl:

Component	Notes
`VLayerMaplibreGeojson`	Standard GeoJSON source + layer
`VLayerMaplibreCluster`	Point clustering
`VLayerMaplibreVector`	Vector tile source
`VLayerMaplibreRaster`	Raster tile source
`VLayerMaplibreImage`	Image source (e.g. radar overlay)
`VLayerMaplibreVideo`	Video source
`VLayerMaplibreCanvas`	Canvas source
`VLayerMaplibrePmtile`	PMTiles archives (uses `pmtiles` — already a hard dep)
`VLayerMaplibreRoute`	Polyline routing
`VLayerMaplibreIsochrone`	Polygon isochrones
`VControlNavigation` / `Scale` / `Geolocate` / `Fullscreen` / `Attribution`	Native MapLibre controls
`VControlLayer` / `VControlLayerGroup` / `VControlLegend`	Visibility + legend controls

deck.gl base (shared by every deck.gl layer)

Every VLayerDeckgl* component goes through a shared MapboxOverlay. Install these once and they cover the whole deck.gl family:

pnpm add @deck.gl/core @deck.gl/mapbox

Most layers additionally need one of the deck.gl module packages below.

deck.gl `@deck.gl/layers` (core 2D primitives)

pnpm add @deck.gl/core @deck.gl/mapbox @deck.gl/layers

Component	Peer dep added
`VLayerDeckglScatterplot`	`@deck.gl/layers`
`VLayerDeckglArc`	`@deck.gl/layers`
`VLayerDeckglGeojson`	`@deck.gl/layers`
`VLayerDeckglPath`	`@deck.gl/layers`
`VLayerDeckglLine`	`@deck.gl/layers`
`VLayerDeckglPolygon`	`@deck.gl/layers`
`VLayerDeckglSolidPolygon`	`@deck.gl/layers`
`VLayerDeckglIcon`	`@deck.gl/layers`
`VLayerDeckglText`	`@deck.gl/layers`
`VLayerDeckglColumn`	`@deck.gl/layers`
`VLayerDeckglBitmap`	`@deck.gl/layers`
`VLayerDeckglGridCell`	`@deck.gl/layers`
`VLayerDeckglPointCloud`	`@deck.gl/layers`
`VLayerDeckgl` (generic)	— (you supply the deck.gl `Layer` instance)

deck.gl `@deck.gl/aggregation-layers` (binning / aggregation)

pnpm add @deck.gl/core @deck.gl/mapbox @deck.gl/aggregation-layers

Component	Peer dep added
`VLayerDeckglHeatmap`	`@deck.gl/aggregation-layers`
`VLayerDeckglHexagon`	`@deck.gl/aggregation-layers`
`VLayerDeckglGrid`	`@deck.gl/aggregation-layers`
`VLayerDeckglContour`	`@deck.gl/aggregation-layers`
`VLayerDeckglScreenGrid`	`@deck.gl/aggregation-layers`

deck.gl `@deck.gl/geo-layers` (tiling + indexing)

pnpm add @deck.gl/core @deck.gl/mapbox @deck.gl/geo-layers

Component	Peer dep added
`VLayerDeckglTrips`	`@deck.gl/geo-layers`
`VLayerDeckglH3Hexagon`	`@deck.gl/geo-layers`
`VLayerDeckglH3Cluster`	`@deck.gl/geo-layers`
`VLayerDeckglMVT`	`@deck.gl/geo-layers`
`VLayerDeckglTile`	`@deck.gl/geo-layers`
`VLayerDeckglTile3D`	`@deck.gl/geo-layers`
`VLayerDeckglTerrain`	`@deck.gl/geo-layers`
`VLayerDeckglGreatCircle`	`@deck.gl/geo-layers`
`VLayerDeckglS2`	`@deck.gl/geo-layers`
`VLayerDeckglGeohash`	`@deck.gl/geo-layers`
`VLayerDeckglQuadkey`	`@deck.gl/geo-layers`
`VLayerDeckglWMS`	`@deck.gl/geo-layers`

deck.gl `@deck.gl/mesh-layers` (3D meshes)

pnpm add @deck.gl/core @deck.gl/mapbox @deck.gl/mesh-layers

Component	Peer dep added
`VLayerDeckglSimpleMesh`	`@deck.gl/mesh-layers`
`VLayerDeckglScenegraph`	`@deck.gl/mesh-layers`

deck.gl raster (COG / Mosaic / MultiCOG)

pnpm add @deck.gl/core @deck.gl/mapbox @deck.gl/layers \
  @developmentseed/deck.gl-geotiff \
  @developmentseed/deck.gl-raster \
  @developmentseed/geotiff \
  @developmentseed/proj

Component	Adds (on top of deck.gl base)
`VLayerCog`	`@deck.gl/layers`, `@developmentseed/deck.gl-geotiff`, `@developmentseed/deck.gl-raster`, `@developmentseed/geotiff`, `@developmentseed/proj`
`VLayerMosaic`	same as COG
`VLayerMultiCog`	same as COG

deck.gl Zarr

pnpm add @deck.gl/core @deck.gl/mapbox \
  @developmentseed/deck.gl-raster \
  @developmentseed/deck.gl-zarr \
  @developmentseed/proj \
  zarrita

Component	Peer deps
`VLayerZarr`	`@developmentseed/deck.gl-raster`, `@developmentseed/deck.gl-zarr`, `@developmentseed/proj`, `zarrita`

deck.gl GeoArrow

Render Apache Arrow Table / RecordBatch data with GeoArrow extension types directly — no GeoJSON parsing. Each layer takes an apache-arrow.Table (or single RecordBatch) as its data prop. No runtime dependency on @geoarrow/deck.gl-geoarrow — the wrappers extract GeoArrow geometry columns and feed flat-buffer attributes to stock @deck.gl/layers (and @deck.gl/geo-layers for trips).

pnpm add @deck.gl/core @deck.gl/mapbox @deck.gl/layers apache-arrow
# +@deck.gl/geo-layers if you use VLayerDeckglGeoArrowTrips

Component	Peer deps
`VLayerDeckglGeoArrowScatterplot`	`@deck.gl/layers`, `apache-arrow`
`VLayerDeckglGeoArrowPath`	`@deck.gl/layers`, `apache-arrow`
`VLayerDeckglGeoArrowPolygon`	`@deck.gl/layers`, `apache-arrow`
`VLayerDeckglGeoArrowSolidPolygon`	`@deck.gl/layers`, `apache-arrow`
`VLayerDeckglGeoArrowText`	`@deck.gl/layers`, `apache-arrow`
`VLayerDeckglGeoArrowTrips`	`@deck.gl/geo-layers`, `apache-arrow`

Wind particles

pnpm add @deck.gl/core @deck.gl/mapbox maplibre-gl-wind

Component	Peer deps
`VLayerWindParticle`	`maplibre-gl-wind` (provides the GPU particle layer)

LiDAR (COPC / LAZ)

pnpm add maplibre-gl-lidar

Component	Peer deps
`VControlLidar`	`maplibre-gl-lidar` (loaded lazily on first mount)

Starfield

pnpm add @geoql/maplibre-gl-starfield

Component	Peer deps
`VLayerStarfield`	`@geoql/maplibre-gl-starfield`

How v-maplibre reports missing peers

When a component initialises and discovers a peer dep is missing, it now throws an error that looks like:

[@geoql/v-maplibre] Missing optional peer dependency "@developmentseed/deck.gl-geotiff".
Install it with: pnpm add @deck.gl/core @deck.gl/layers @deck.gl/mapbox \
  @developmentseed/deck.gl-geotiff @developmentseed/deck.gl-raster \
  @developmentseed/geotiff @developmentseed/proj
Original error: Cannot find module '@developmentseed/deck.gl-geotiff'

This is produced by the public requirePeer helper, which is also exported from the package if you need to wrap your own dynamic peer-dep loads:

import { requirePeer } from '@geoql/v-maplibre';

const { LidarControl } = await requirePeer(
  'maplibre-gl-lidar',
  () => import('maplibre-gl-lidar'),
);

Next: see the Getting Started guide for the minimal setup, then explore the Layer docs for component-by-component reference.

Edit this pageorReport an issue

Getting Started

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

Examples

Practical examples for using v-maplibre components