---
title: "Vue + Vite"
description: "Use @movk/maplibre/vite and vue-plugin to work with the same components in a plain Vue + Vite project."
canonical_url: "https://maplibre.mhaibaraai.cn/en/docs/getting-started/vue"
---
# Vue + Vite

> Use @movk/maplibre/vite and vue-plugin to work with the same components in a plain Vue + Vite project.

## Vite Plugin

Add the plugin to `vite.config.ts` to enable auto-importing of components and composables:

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import Maplibre from '@movk/maplibre/vite'

export default defineConfig({
  plugins: [vue(), Maplibre()]
})
```

`Maplibre()` automatically registers the component resolver and auto-import entries — just use it directly in a standalone Vue + Vite project.

## Reusing an Existing unplugin Instance

Some libraries (e.g. `@nuxt/ui`) ship a Vite plugin with a single built-in `unplugin-vue-components` / `unplugin-auto-import` instance. In that case, skip `Maplibre()` and instead inject the `maplibreComponentResolver` and `maplibreAutoImports` exports from `@movk/maplibre/unplugin` into the host plugin:

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
import { maplibreAutoImports, maplibreComponentResolver } from '@movk/maplibre/unplugin'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      components: { resolvers: [maplibreComponentResolver()] },
      autoImport: { imports: [...maplibreAutoImports()] }
    })
  ]
})
```

> [!NOTE]
> 
> @nuxt/ui
> 
>  throws an error when it detects a second 
> 
> unplugin-vue-components
> 
>  / 
> 
> unplugin-auto-import
> 
>  instance. When using it alongside 
> 
> @nuxt/ui
> 
> , always use the injection approach — do not stack 
> 
> Maplibre()
> 
>  on top.

`maplibreComponentResolver` uses `Maplibre` as the component prefix by default; customize it with `maplibreComponentResolver({ prefix: 'Mb' })`.

## Register the Vue Plugin

In your entry file, register the `vue-plugin`, optionally pass the Tianditu token and font config, and import the runtime styles:

```ts [main.ts]
import { createApp } from 'vue'
import MaplibrePlugin from '@movk/maplibre/vue-plugin'
import '@movk/maplibre/index.css'
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url'
import App from './App.vue'

createApp(App)
  .use(MaplibrePlugin, {
    workerUrl,
    tk: import.meta.env.VITE_TIANDITU_TK,
    glyphs: 'https://tiles.openfreemap.org/fonts/{fontstack}/{range}.pbf',
    textFont: ['Noto Sans Regular']
  })
  .mount('#app')
```

> [!WARNING]
> 
> When bundled by Vite or other bundlers, maplibre-gl v6 cannot resolve its worker URL automatically. You must pass 
> 
> workerUrl
> 
>  (imported with 
> 
> ?worker&url
> 
>  so Vite emits a self-contained worker file); otherwise data layers such as vector tiles, GeoJSON and drawing will not render. The Nuxt module handles this automatically.

A matching `.env`:

```bash [.env]
VITE_TIANDITU_TK=your_tianditu_tk
```

> [!NOTE]
> 
> tk
> 
>  is the browser-type key (Referer-checked), used only for Tianditu basemap tiles. Tianditu's search / geocoding / administrative division / routing web services are server-only (IP allowlist-checked) — they cannot be injected via 
> 
> vue-plugin
> 
> , nor placed in 
> 
> VITE_
> 
> -prefixed env vars (which get inlined into the client bundle). Call them from your own server (Nuxt Nitro, a Vite dev middleware, etc.) with 
> 
> createTianditu
> 
> ; see 
> 
> Tianditu Web Services
> 
> .

## Identical Usage

Components and composables are auto-imported by `@movk/maplibre/vite`, and the usage is identical to Nuxt:

```vue [App.vue]
<script setup lang="ts">
const center = ref<[number, number]>([116.397, 39.908])
</script>

<template>
  <div style="height: 480px">
    <MaplibreMap v-model:center="center" :options="{ style: 'https://tiles.openfreemap.org/styles/liberty', zoom: 9 }">
      <MaplibreNavigationControl position="top-right" />
    </MaplibreMap>
  </div>
</template>
```


## Sitemap

See the full [sitemap](https://maplibre.mhaibaraai.cn/sitemap.md) for all pages.