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

> Use @movk/mapbox/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 Mapbox from '@movk/mapbox/vite'

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

`Mapbox()` 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 `Mapbox()` and instead inject the `mapboxComponentResolver` and `mapboxAutoImports` exports from `@movk/mapbox/unplugin` into the host plugin:

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
import { mapboxAutoImports, mapboxComponentResolver } from '@movk/mapbox/unplugin'

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

> [!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 
> 
> Mapbox()
> 
>  on top.

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

## Register the Vue Plugin

In your entry file, register the `vue-plugin`, pass in your tokens, and import the runtime styles:

```ts [main.ts]
import { createApp } from 'vue'
import MapboxPlugin from '@movk/mapbox/vue-plugin'
import '@movk/mapbox/index.css'
import App from './App.vue'

createApp(App)
  .use(MapboxPlugin, {
    accessToken: import.meta.env.VITE_MAPBOX_TOKEN,
    tiandituToken: import.meta.env.VITE_TIANDITU_TOKEN
  })
  .mount('#app')
```

A matching `.env`:

```bash [.env]
VITE_MAPBOX_TOKEN=pk.your_mapbox_access_token
VITE_TIANDITU_TOKEN=your_tianditu_tk
```

> [!NOTE]
> 
> tiandituToken
> 
>  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/mapbox/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">
    <MapboxMap v-model:center="center" :options="{ style: 'mapbox://styles/mapbox/streets-v12', zoom: 9 }">
      <MapboxNavigationControl position="top-right" />
    </MapboxMap>
  </div>
</template>
```


## Sitemap

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