---
title: "Nuxt 4"
description: "Register the @movk/mapbox module in Nuxt 4, configure tokens, and get components and composables auto-imported."
canonical_url: "https://mapbox.mhaibaraai.cn/en/docs/getting-started/nuxt"
---
# Nuxt 4

> Register the @movk/mapbox module in Nuxt 4, configure tokens, and get components and composables auto-imported.

## Register the Module

Register the module in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@movk/mapbox']
})
```

Tokens are read from environment variables — no explicit declaration in `nuxt.config.ts` is needed:

```bash [.env]
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your_mapbox_access_token
NUXT_PUBLIC_MAPBOX_TIANDITU_TOKEN=your_tianditu_tk
```

> [!NOTE]
> 
> Tokens are written to 
> 
> runtimeConfig.public.mapbox
> 
>  and read by components when the map is created on the client. Do not hardcode them.

## Explicit Configuration

When a token has to be computed or comes from several sources, pass it explicitly through the `mapbox` option:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@movk/mapbox'],
  mapbox: {
    accessToken: process.env.MY_MAPBOX_TOKEN,
    tiandituToken: process.env.MY_TIANDITU_TOKEN
  }
})
```

The two approaches play different roles:

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      When it applies
    </th>
    
    <th>
      Variable name
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        mapbox
      </code>
      
       option
    </td>
    
    <td>
      Evaluated once at build time
    </td>
    
    <td>
      Anything you choose
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN
      </code>
    </td>
    
    <td>
      Build-time fallback, overridable at runtime
    </td>
    
    <td>
      Fixed by Nuxt's <code>
        runtimeConfig
      </code>
      
       mapping rules
    </td>
  </tr>
</tbody>
</table>

Once the `runtimeConfig.public.mapbox.accessToken` key is declared, `NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN` overrides it at runtime — even if you passed a value through the `mapbox` option. Conversely, a custom name such as `MY_MAPBOX_TOKEN` takes no part in `runtimeConfig` mapping, so changing it requires a rebuild.

> [!WARNING]
> 
> If your site is prerendered (
> 
> nitro.prerender
> 
> ) or built with 
> 
> nuxt generate
> 
> , tokens are baked into the static HTML at 
> 
> build time
> 
>  and runtime overrides have no effect on already-generated pages. Either way, the build process must have access to the token.

## Module Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Environment Variable
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        accessToken
      </code>
    </td>
    
    <td>
      <code>
        NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN
      </code>
    </td>
    
    <td>
      Mapbox access token
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tiandituToken
      </code>
    </td>
    
    <td>
      <code>
        NUXT_PUBLIC_MAPBOX_TIANDITU_TOKEN
      </code>
    </td>
    
    <td>
      Tianditu service <code>
        tk
      </code>
      
       (required when using <code>
        MapboxTiandituLayer
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prefix
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Component prefix, defaults to <code>
        Mapbox
      </code>
    </td>
  </tr>
</tbody>
</table>

## `optimizeDeps` `v1.0.1+`

> [!TIP]
> 
> Since 
> 
> 1.0.1
> 
> , the module automatically registers the CJS dependencies it uses (
> 
> mapbox-gl
> 
> , 
> 
> lottie-web
> 
> ) into Vite's 
> 
> optimizeDeps.include
> 
>  internally — 
> 
> no manual configuration is needed in your app's 
> 
> nuxt.config.ts
> 
> .

If you still encounter named-export errors in special build or deployment environments, you can fall back to manual configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vite: {
    optimizeDeps: {
      include: ['mapbox-gl']
    }
  }
})
```

## Getting Started

Components and composables are auto-imported — no manual imports needed. The map instance is only created on the client inside `onMounted`, so all components are SSR-safe; **no <ClientOnly> wrapper is required**:

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

<template>
  <MapboxMap
    v-model:center="center"
    v-model:zoom="zoom"
    :options="{ style: 'mapbox://styles/mapbox/streets-v12' }"
  >
    <MapboxLayer
      layer-id="points"
      type="circle"
      :source="{ type: 'geojson', data: '/points.geojson' }"
      :paint="{ 'circle-radius': 8, 'circle-color': '#e11d48' }"
    />
    <MapboxNavigationControl position="top-right" />
  </MapboxMap>
</template>
```

> [!WARNING]
> 
> MapboxMap
> 
>  sets 
> 
> width: 100%; height: 100%
> 
>  on its container. Make sure the parent element has an explicit height, otherwise the map will not be visible.


## Sitemap

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