---
title: "Getting Started"
description: "Get started with v-maplibre in your Vue 3 or Nuxt project"
canonical_url: "https://v-maplibre.geoql.in/guide/getting-started"
---
# Getting Started

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

## Installation

<callout icon="i-lucide-package-check" color="success">

**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](#optional-packages) below.

</callout>

Install the library and its single peer dependency:

<code-group>

```bash [pnpm]
pnpm add @geoql/v-maplibre maplibre-gl
```

```bash [npm]
npm install @geoql/v-maplibre maplibre-gl
```

```bash [yarn]
yarn add @geoql/v-maplibre maplibre-gl
```

</code-group>

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:

```typescript
// 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](https://github.com/geoql/v-maplibre/issues/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:

```typescript
// 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);
```

<callout icon="i-lucide-info">

The `?worker&url` import is Vite-specific. Consumers on other bundlers need no override — the shipped worker covers them.

</callout>

## Basic Usage

Here's a simple example to render a map:

```vue
<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:

```vue
<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:

```typescript
// 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:

```typescript
// 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:

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      Components
    </th>
    
    <th>
      Install
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      deck.gl base
    </td>
    
    <td>
      <code>
        VLayerDeckgl
      </code>
      
      , <code>
        VLayerDeckglScatterplot
      </code>
      
      , <code>
        VLayerDeckglArc
      </code>
      
      , <code>
        VLayerDeckglLine
      </code>
      
      , <code>
        VLayerDeckglPath
      </code>
      
      , <code>
        VLayerDeckglPolygon
      </code>
      
      , <code>
        VLayerDeckglSolidPolygon
      </code>
      
      , <code>
        VLayerDeckglGeojson
      </code>
      
      , <code>
        VLayerDeckglIcon
      </code>
      
      , <code>
        VLayerDeckglText
      </code>
      
      , <code>
        VLayerDeckglColumn
      </code>
      
      , <code>
        VLayerDeckglBitmap
      </code>
      
      , <code>
        VLayerDeckglPointCloud
      </code>
    </td>
    
    <td>
      <code>
        pnpm add @deck.gl/core @deck.gl/layers @deck.gl/mapbox
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Aggregation
    </td>
    
    <td>
      <code>
        VLayerDeckglHeatmap
      </code>
      
      , <code>
        VLayerDeckglHexagon
      </code>
      
      , <code>
        VLayerDeckglGrid
      </code>
      
      , <code>
        VLayerDeckglGridCell
      </code>
      
      , <code>
        VLayerDeckglContour
      </code>
      
      , <code>
        VLayerDeckglScreenGrid
      </code>
    </td>
    
    <td>
      <code>
        pnpm add @deck.gl/aggregation-layers
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Geo / tiles
    </td>
    
    <td>
      <code>
        VLayerDeckglTrips
      </code>
      
      , <code>
        VLayerDeckglMVT
      </code>
      
      , <code>
        VLayerDeckglTile
      </code>
      
      , <code>
        VLayerDeckglTile3D
      </code>
      
      , <code>
        VLayerDeckglTerrain
      </code>
      
      , <code>
        VLayerDeckglH3Hexagon
      </code>
      
      , <code>
        VLayerDeckglH3Cluster
      </code>
      
      , <code>
        VLayerDeckglS2
      </code>
      
      , <code>
        VLayerDeckglGeohash
      </code>
      
      , <code>
        VLayerDeckglQuadkey
      </code>
      
      , <code>
        VLayerDeckglGreatCircle
      </code>
      
      , <code>
        VLayerDeckglWMS
      </code>
    </td>
    
    <td>
      <code>
        pnpm add @deck.gl/geo-layers
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      3D mesh
    </td>
    
    <td>
      <code>
        VLayerDeckglSimpleMesh
      </code>
      
      , <code>
        VLayerDeckglScenegraph
      </code>
    </td>
    
    <td>
      <code>
        pnpm add @deck.gl/mesh-layers
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Raster (COG)
    </td>
    
    <td>
      <code>
        VLayerCog
      </code>
      
      , <code>
        VLayerMultiCog
      </code>
      
      , <code>
        VLayerMosaic
      </code>
    </td>
    
    <td>
      <code>
        pnpm add @developmentseed/deck.gl-geotiff @developmentseed/deck.gl-raster @developmentseed/geotiff @developmentseed/proj
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Zarr
    </td>
    
    <td>
      <code>
        VLayerZarr
      </code>
    </td>
    
    <td>
      <code>
        pnpm add @developmentseed/deck.gl-zarr zarrita
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      GeoArrow
    </td>
    
    <td>
      <code>
        VLayerDeckglGeoArrowScatterplot
      </code>
      
      , <code>
        VLayerDeckglGeoArrowPath
      </code>
      
      , <code>
        VLayerDeckglGeoArrowPolygon
      </code>
      
      , <code>
        VLayerDeckglGeoArrowSolidPolygon
      </code>
      
      , <code>
        VLayerDeckglGeoArrowText
      </code>
      
      , <code>
        VLayerDeckglGeoArrowTrips
      </code>
    </td>
    
    <td>
      <code>
        pnpm add @deck.gl/layers apache-arrow
      </code>
      
       (<code>
        + @deck.gl/geo-layers
      </code>
      
       for trips)
    </td>
  </tr>
  
  <tr>
    <td>
      Wind particles
    </td>
    
    <td>
      <code>
        VLayerWindParticle
      </code>
    </td>
    
    <td>
      <code>
        pnpm add maplibre-gl-wind
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      LiDAR
    </td>
    
    <td>
      <code>
        VControlLidar
      </code>
    </td>
    
    <td>
      <code>
        pnpm add maplibre-gl-lidar
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Starfield
    </td>
    
    <td>
      <code>
        VLayerStarfield
      </code>
    </td>
    
    <td>
      <code>
        pnpm add @geoql/maplibre-gl-starfield three
      </code>
    </td>
  </tr>
</tbody>
</table>

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

<u-page-links :links="[{"label":"Components","description":"Explore all available components","icon":"i-lucide-map","to":"/components/map"},{"label":"Live Examples","description":"50+ interactive demos","icon":"i-lucide-code","to":"https://mapcn-vue.geoql.in/examples"},{"label":"deck.gl Layers","description":"High-performance WebGL layers","icon":"i-lucide-layers","to":"/layers/deckgl-overview"}]">



</u-page-links>


## Sitemap

See the full [sitemap](https://v-maplibre.geoql.in/sitemap.md) for all pages.