@geoql/v-maplibre

中文文档
3.1.2发布于 2026/11/08MITTypeScriptES Module构建来源已验证近 30 天下载 1.3万

Vue 3 components for MapLibre GL - reactive map components with full TypeScript support

原始使用文档
文档目录19 节
  1. Features
  2. Installation
  3. Optional peer dependencies
  4. MapLibre GL v6 worker
  5. Migrating to v2.0.0
  6. Quick Start
  7. Components
  8. Core Components
  9. MapLibre Layer Components
  10. deck.gl Layer Components
  11. Control Components
  12. deck.gl Example
  13. Wind Visualization Example
  14. Usage with Nuxt
  15. TypeScript Support
  16. Development
  17. License
  18. Credits
  19. Contributing

@geoql/v-maplibre

Vue 3 components for MapLibre GL - Build beautiful, reactive map applications

npm version JSR License: MIT

Using shadcn-vue? Check out mapcn-vue for copy-paste map components styled with Tailwind CSS.

Features

  • 🗺️ Full MapLibre GL Support - Complete wrapper around MapLibre GL JS
  • 🔥 Vue 3 Composition API - Built with modern Vue 3 patterns
  • 📦 TypeScript First - Fully typed with excellent IDE support
  • 🎨 Reactive Components - Reactive and composable map components
  • 🚀 Nuxt 4 Ready - Seamlessly works with Nuxt 4 and SSR
  • 🎯 PMTiles Built-in - Native support for PMTiles protocol
  • 🌐 deck.gl Integration - High-performance WebGL visualization layers
  • 🛰️ COG/GeoTIFF Support - GPU-accelerated Cloud-Optimized GeoTIFF layers
  • 📡 LiDAR Viewer - LAS/LAZ/COPC point cloud visualization with streaming

Installation

The library has two required dependencies. Everything else is opt-in per feature.

# pnpm (recommended)
pnpm add @geoql/v-maplibre maplibre-gl

# npm
npm install @geoql/v-maplibre maplibre-gl

# yarn
yarn add @geoql/v-maplibre maplibre-gl

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

Optional peer dependencies

Add these only for the layers you actually use — picking what you need keeps your bundle lean. Since v2.0.0, each group is imported from a dedicated subpath (@geoql/v-maplibre/deck.gl, /geotiff, /wind, /lidar, /starfield) so the core entry never references deck.gl — see Migrating to v2.0.0.

# deck.gl base — import from '@geoql/v-maplibre/deck.gl'
# VLayerDeckgl, VLayerDeckglScatterplot, VLayerDeckglArc,
# VLayerDeckglLine, VLayerDeckglPath, VLayerDeckglPolygon, VLayerDeckglSolidPolygon,
# VLayerDeckglGeojson, VLayerDeckglIcon, VLayerDeckglText, VLayerDeckglColumn,
# VLayerDeckglBitmap, VLayerDeckglPointCloud
pnpm add @deck.gl/core @deck.gl/layers @deck.gl/mapbox

# Aggregation — VLayerDeckglHeatmap, VLayerDeckglHexagon, VLayerDeckglGrid,
# VLayerDeckglGridCell, VLayerDeckglContour, VLayerDeckglScreenGrid
pnpm add @deck.gl/aggregation-layers

# Geo / tiles — VLayerDeckglTrips, VLayerDeckglMVT, VLayerDeckglTile,
# VLayerDeckglTile3D, VLayerDeckglTerrain, VLayerDeckglH3Hexagon,
# VLayerDeckglH3Cluster, VLayerDeckglS2, VLayerDeckglGeohash,
# VLayerDeckglQuadkey, VLayerDeckglGreatCircle, VLayerDeckglWMS
pnpm add @deck.gl/geo-layers

# 3D mesh — VLayerDeckglSimpleMesh, VLayerDeckglScenegraph
pnpm add @deck.gl/mesh-layers

# Cloud-Optimized GeoTIFF — import from '@geoql/v-maplibre/geotiff'
# VLayerCog, VLayerMultiCog, VLayerMosaic
pnpm add @developmentseed/deck.gl-geotiff @developmentseed/deck.gl-raster @developmentseed/geotiff @developmentseed/proj

# Zarr — import from '@geoql/v-maplibre/geotiff'
# VLayerZarr
pnpm add @developmentseed/deck.gl-zarr zarrita

# GeoArrow — import from '@geoql/v-maplibre/deck.gl'
# VLayerDeckglGeoArrowScatterplot, VLayerDeckglGeoArrowPath,
# VLayerDeckglGeoArrowPolygon, VLayerDeckglGeoArrowSolidPolygon,
# VLayerDeckglGeoArrowText, VLayerDeckglGeoArrowTrips
# (Trips additionally needs @deck.gl/geo-layers — already covered by the
#  deck.gl tile/route line above.)
pnpm add apache-arrow

# Wind particles — import from '@geoql/v-maplibre/wind'
# VLayerWindParticle
# (Wind-data helpers — createWindDataFromOpenWeatherMap, generateWindTexture,
# WindParticleLayer — must be imported directly from 'maplibre-gl-wind'.)
pnpm add maplibre-gl-wind

# LiDAR point cloud viewer — import from '@geoql/v-maplibre/lidar'
# VControlLidar
pnpm add maplibre-gl-lidar

# Three.js starfield skybox for globe projections — import from '@geoql/v-maplibre/starfield'
# VLayerStarfield
pnpm add @geoql/maplibre-gl-starfield three

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

MapLibre GL v6 worker

MapLibre GL v6 resolves its worker with a URL it builds at runtime, which bundlers cannot see — the request 404s unless the worker URL is wired by hand (#160). VMap handles it for you: it points MapLibre at a self-contained worker that ships with the library, using the standard new URL('./maplibre-worker.js', import.meta.url) pattern — Vite (dev + build) and webpack 5 both emit that file 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:

// app/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);

?worker&url is Vite-specific. On other bundlers keep the shipped worker — no override is needed.

Migrating to v2.0.0

v2.0.0 moves the optional-peer layers off the root entry onto dedicated subpaths so a core-only install no longer transitively references deck.gl / lidar / wind (fixes #114). Core components are unchanged — keep importing VMap, VMarker, VPopup, every VControl* (except VControlLidar), and every VLayerMaplibre* (except VLayerStarfield) from @geoql/v-maplibre. Only update the optional-peer components:

ComponentsNew import
All VLayerDeckgl* (base, aggregation, geo, mesh, GeoArrow)@geoql/v-maplibre/deck.gl
VLayerCog/MultiCog/Mosaic/Zarr@geoql/v-maplibre/geotiff
VLayerWindParticle@geoql/v-maplibre/wind
VLayerStarfield@geoql/v-maplibre/starfield
VControlLidar@geoql/v-maplibre/lidar
- import { VMap, VLayerDeckglScatterplot } from '@geoql/v-maplibre';
+ import { VMap } from '@geoql/v-maplibre';
+ import { VLayerDeckglScatterplot } from '@geoql/v-maplibre/deck.gl';

Component-specific TypeScript types (e.g. MosaicSource, WindDataPoint, LidarControlOptions) move to the same subpath as their component.

Quick Start

<script setup lang="ts">
  import { VMap, VMarker } 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">
    <VMarker :coordinates="[-74.5, 40]"></VMarker>
  </VMap>
</template>

Components

Core Components

  • VMap - Main map component
  • VMarker - Interactive markers
  • VPopup - Popups and tooltips

MapLibre Layer Components

  • VLayerMaplibreGeojson - GeoJSON layers
  • VLayerMaplibreVector - Vector tile layers
  • VLayerMaplibreRaster - Raster tile layers
  • VLayerMaplibreImage - Image layers
  • VLayerMaplibreVideo - Video layers
  • VLayerMaplibreCanvas - Canvas layers
  • VLayerMaplibreCluster - Clustered point layers
  • VLayerMaplibrePmtile - PMTiles layers
  • VLayerMaplibreHillshade - Hillshade relief from a raster-dem source
  • VTerrain - Native MapLibre 3D terrain (map.setTerrain)
  • VSky - Sky, horizon and fog for pitched 3D views (map.setSky)
  • VLayerMaplibreRoute - Route/delivery tracking visualization
  • VLayerStarfield - Three.js starfield skybox for globe projections (requires @geoql/maplibre-gl-starfield, three)

deck.gl Layer Components

High-performance WebGL visualization layers powered by deck.gl:

Core Layers

  • VLayerDeckglScatterplot - Circles/points
  • VLayerDeckglArc - Origin-destination arcs
  • VLayerDeckglLine - Flat lines
  • VLayerDeckglPath - Polylines/routes
  • VLayerDeckglPolygon - Filled polygons
  • VLayerDeckglGeojson - GeoJSON features
  • VLayerDeckglIcon - Custom markers
  • VLayerDeckglText - Text labels
  • VLayerDeckglColumn - 3D columns
  • VLayerDeckglBitmap - Georeferenced images

Aggregation Layers

  • VLayerDeckglHeatmap - Density heatmap
  • VLayerDeckglHexagon - Hexagonal binning
  • VLayerDeckglGrid - Square grid aggregation
  • VLayerDeckglContour - Contour/isolines
  • VLayerDeckglScreenGrid - Screen-space grid

Geo Layers

  • VLayerDeckglTrips - Animated paths
  • VLayerDeckglMVT - Mapbox Vector Tiles
  • VLayerDeckglTile - Generic tiles
  • VLayerDeckglTile3D - 3D Tiles (Cesium)
  • VLayerDeckglTerrain - Terrain mesh
  • VLayerDeckglH3Hexagon - H3 hexagons
  • VLayerDeckglH3Cluster - Clustered H3 hexagon regions
  • VLayerDeckglGreatCircle - Great circle arcs
  • VLayerDeckglWMS - Web Map Service tiles

Tile System Layers

  • VLayerDeckglS2 - Google S2 geometry cells
  • VLayerDeckglGeohash - Geohash spatial indexing
  • VLayerDeckglQuadkey - Bing Maps Quadkey tiles
  • VLayerDeckglGridCell - Pre-aggregated grid cells

Mesh Layers

  • VLayerDeckglSimpleMesh - 3D meshes
  • VLayerDeckglScenegraph - glTF/GLB models

Point Cloud Layers

  • VLayerDeckglPointCloud - LiDAR/photogrammetry point clouds
  • VLayerDeckglSolidPolygon - 3D extruded solid polygons

Raster Layers (requires @developmentseed/deck.gl-raster and @developmentseed/deck.gl-geotiff)

  • VLayerCog - Cloud-Optimized GeoTIFF visualization (GPU-accelerated, auto-reprojection)
  • VLayerMosaic - Client-side COG mosaic from STAC items (requires flatbush, proj4)

GeoArrow Layers (requires @deck.gl/layers + apache-arrow; trips also needs @deck.gl/geo-layers)

Render Apache Arrow Table / RecordBatch data with GeoArrow extension types directly — no GeoJSON parsing. Ideal for GeoParquet / Arrow IPC sources and very large point/polygon datasets. The wrappers extract GeoArrow geometry columns inside the Vue wrapper and feed flat-buffer attributes to stock deck.gl layers — no @geoarrow/deck.gl-geoarrow runtime dependency.

  • VLayerDeckglGeoArrowScatterplot - Points from a GeoArrow point / multipoint column
  • VLayerDeckglGeoArrowPath - Polylines from a GeoArrow linestring / multilinestring column
  • VLayerDeckglGeoArrowPolygon - Filled + stroked polygons from a GeoArrow polygon / multipolygon column
  • VLayerDeckglGeoArrowSolidPolygon - 3D extruded polygons (height-mapped choropleths, building footprints)
  • VLayerDeckglGeoArrowText - Text labels at GeoArrow point positions
  • VLayerDeckglGeoArrowTrips - Animated trips along GeoArrow linestrings with per-vertex timestamps

Wind Visualization (requires maplibre-gl-wind)

  • VLayerWindParticle - Animated wind particle flow with speed-based color ramps

The wind-data helpers (createWindDataFromOpenWeatherMap, generateWindTexture, WindParticleLayer, windUniforms) are not re-exported from @geoql/v-maplibre. Import them directly from maplibre-gl-wind:

import { createWindDataFromOpenWeatherMap } from 'maplibre-gl-wind';

Generic Layer

  • VLayerDeckgl - Use any deck.gl layer class directly

Control Components

  • VControlNavigation - Navigation controls (zoom, rotate)
  • VControlScale - Scale indicator
  • VControlGeolocate - Geolocation control
  • VControlFullscreen - Fullscreen toggle
  • VControlAttribution - Attribution control
  • VControlLidar - LiDAR point cloud viewer (LAS/LAZ/COPC support, streaming, color schemes)

deck.gl Example

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

  const mapOptions = {
    style: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
    center: [-122.4, 37.8],
    zoom: 11,
  };

  const data = [
    { coordinates: [-122.4, 37.8], size: 100 },
    { coordinates: [-122.5, 37.7], size: 200 },
  ];
</script>

<template>
  <VMap :options="mapOptions" style="height: 500px">
    <VLayerDeckglScatterplot
      id="points"
      :data="data"
      :get-position="(d) => d.coordinates"
      :get-radius="(d) => d.size"
      :get-fill-color="[255, 140, 0]"
      :radius-min-pixels="5"
      :pickable="true"
      @click="(info) => console.log('Clicked:', info.object)"
    ></VLayerDeckglScatterplot>
  </VMap>
</template>

Wind Visualization Example

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

  const mapOptions = {
    style: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
    center: [0, 20],
    zoom: 2,
  };

  // Wind data points with speed (m/s) and direction (degrees, 0=North)
  const windData = [
    { lat: 40.7, lon: -74.0, speed: 5.2, direction: 180 },
    { lat: 34.0, lon: -118.2, speed: 3.1, direction: 270 },
    // ... more points
  ];
</script>

<template>
  <VMap :options="mapOptions" style="height: 500px">
    <VLayerWindParticle
      id="wind"
      :wind-data="windData"
      :num-particles="8192"
      :speed-factor="50"
      :color-ramp="[
        [0.0, [59, 130, 189, 255]],
        [0.5, [253, 174, 97, 255]],
        [1.0, [213, 62, 79, 255]],
      ]"
      :speed-range="[0, 30]"
    ></VLayerWindParticle>
  </VMap>
</template>

Usage with Nuxt

For Nuxt applications, wrap the map component with ClientOnly:

<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>

Add styles to your nuxt.config.ts:

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

TypeScript Support

All components are fully typed. Import types as needed:

import type { MapOptions, LngLatLike } from 'maplibre-gl';
import type { Color, PickingInfo } from '@deck.gl/core';

Development

This package is part of the v-maplibre monorepo.

# Clone and install (from monorepo root)
git clone https://github.com/geoql/v-maplibre.git
cd v-maplibre
pnpm install

# Build this package
pnpm --filter @geoql/v-maplibre run build

# Run tests
pnpm run test

# Watch mode
pnpm run dev:lib

License

MIT License - see LICENSE for details

Credits

Built with:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.


Made with ❤️ by GeoQL

版本与发布记录

@geoql/v-maplibre 共发布 30 个版本,首次发布于 2025/11/25;过去 12 个月发布了 30 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.1.2latest2026/11/088 天前
3.1.12026/11/079 天前
3.1.02026/10/2819 天前
3.0.12026/09/191 个月前
3.0.02026/08/153 个月前
2.0.12026/06/155 个月前

关于 @geoql/v-maplibre 的常见问题

@geoql/v-maplibre 是什么?

Vue 3 components for MapLibre GL - reactive map components with full TypeScript support

如何安装 @geoql/v-maplibre?

在项目目录运行 npm install @geoql/v-maplibre,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:vue(^3.5.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geoql/v-maplibre 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geoql/v-maplibre 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geoql/v-maplibre 可以商用吗?

@geoql/v-maplibre 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geoql/v-maplibre 的下载量有多少?

根据 npm 官方下载统计,@geoql/v-maplibre 在 2026/10/16 – 2026/11/14 这 30 天内被下载 13,071 次,日均约 436 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geoql/v-maplibre 还在维护吗?

最新版本 3.1.2 发布于 2026/11/08(8 天前);至今共发布 30 个版本,其中过去 12 个月发布了 30 个;首次发布于 2025/11/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。