Installation

What you're adding

• 2 packages minimum in your dependency graph (@geoql/v-maplibre + maplibre-gl), or up to 12 packages if you opt into the full deck.gl + GeoTIFF/Zarr/raster/GeoArrow stack
• ~120 kB minified JS + ~12.7 kB CSS for the full library, tree-shakeable down to only the components you import
• 5 peer-dependency tiers — Required (Vue 3 + MapLibre GL JS ^5.24.0) → +deck.gl base (@deck.gl/core, @deck.gl/layers, @deck.gl/mapbox ^9.3.0) → +aggregation/geo/mesh (@deck.gl/aggregation-layers, @deck.gl/geo-layers, @deck.gl/mesh-layers) → +raster/Zarr (@developmentseed/deck.gl-raster, @developmentseed/deck.gl-zarr, @developmentseed/deck.gl-geotiff ^0.6.0) → +GeoArrow (apache-arrow ^17.0.0)
• Node.js 20+ and any modern package manager (pnpm 11+ is what we use in CI)

Prerequisites

Before you begin, make sure you have:

• A Vue 3 or Nuxt 3+ project
• Tailwind CSS v4 configured
• shadcn-vue initialized (optional, but recommended)

Quick Start

The easiest way to add mapcn-vue components is using the shadcn-vue CLI:

# Add the base map component
npx shadcn-vue@latest add https://mapcn-vue.geoql.in/r/map.json

# Add MapLibre layers
npx shadcn-vue@latest add https://mapcn-vue.geoql.in/r/map-layers.json

# Add deck.gl core layers
npx shadcn-vue@latest add https://mapcn-vue.geoql.in/r/map-deckgl-core.json

Manual Installation

If you prefer to install manually:

1. Install dependencies

# Core dependencies (use your preferred package manager)
pnpm add @geoql/v-maplibre maplibre-gl @vueuse/core
# or: npm install @geoql/v-maplibre maplibre-gl @vueuse/core
# or: yarn add @geoql/v-maplibre maplibre-gl @vueuse/core

# For deck.gl layers (optional)
pnpm add @deck.gl/core @deck.gl/layers @deck.gl/mapbox
pnpm add @deck.gl/aggregation-layers  # Heatmap, Hexagon, Grid
pnpm add @deck.gl/geo-layers          # Trips, MVT, Tile
pnpm add @deck.gl/mesh-layers         # SimpleMesh, Scenegraph

2. Add CSS

Import the MapLibre CSS in your main entry file or Nuxt config:

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

3. Copy components

Copy the components you need from the GitHub repository into your project.

Usage

Once installed, you can use the components in your Vue templates:

<script setup lang="ts">
  import { Map, MapMarker, MapControls } from '@/components/ui/map';

  const mapOptions = {
    style: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
    center: [-74.006, 40.7128],
    zoom: 11,
  };
</script>

<template>
  <Map :options="mapOptions" class="h-125">
    <MapControls />
    <MapMarker :coordinates="[-74.006, 40.7128]" />
  </Map>
</template>

Nuxt Usage

For Nuxt applications, wrap map components with ClientOnly:

<template>
  <ClientOnly>
    <Map :options="mapOptions">
      <MapControls />
    </Map>
    <template #fallback>
      <div class="h-125 flex items-center justify-center">Loading map...</div>
    </template>
  </ClientOnly>
</template>

Sources