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

> Register the @movk/maplibre module in Nuxt 4, optionally configure the Tianditu token and fonts, 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/maplibre']
})
```

MapLibre needs no access token. When using Tianditu basemaps, the Tianditu `tk` is read from an environment variable:

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

> [!NOTE]
> 
> Config is written to 
> 
> runtimeConfig.public.maplibre
> 
>  and read by components when the map is created on the client. Do not hardcode tokens.

## Fonts

When `style` is omitted, `MaplibreMap` uses a blank style that has no glyphs URL, so text labels cannot render. The library's built-in text layers (cluster counts, measure labels) use MapLibre's default font stack, which most public font services do not serve. When you need text, set a font service and font stack explicitly:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@movk/maplibre'],
  maplibre: {
    glyphs: 'https://tiles.openfreemap.org/fonts/{fontstack}/{range}.pbf',
    textFont: ['Noto Sans Regular']
  }
})
```

> [!TIP]
> 
> CJK characters are drawn with local browser fonts by default; the font service mainly affects digits and Latin characters.

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

## Module Options

| Option | Environment Variable | Description |
| --- | --- | --- |
| `tk` | `NUXT_PUBLIC_MAPLIBRE_TK` | Tianditu service `tk` (required when using `MaplibreTiandituLayer`) |
| `glyphs` | — | Font pbf URL template for the blank style (with `{fontstack}` and `{range}`) |
| `textFont` | — | Font stack for the library's built-in text layers |
| `prefix` | — | Component prefix, defaults to `Maplibre` |

## `optimizeDeps`

> [!TIP]
> 
> The module automatically registers its CJS dependency 
> 
> lottie-web
> 
>  into Vite's 
> 
> optimizeDeps.include
> 
>  — 
> 
> no manual configuration is needed in your app's 
> 
> nuxt.config.ts
> 
> ; 
> 
> maplibre-gl
> 
>  is native ESM and needs no pre-bundling.

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: ['lottie-web']
    }
  }
})
```

## 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>
  <MaplibreMap
    v-model:center="center"
    v-model:zoom="zoom"
    :options="{ style: 'https://tiles.openfreemap.org/styles/liberty' }"
  >
    <MaplibreLayer
      layer-id="points"
      type="circle"
      :source="{ type: 'geojson', data: '/points.geojson' }"
      :paint="{ 'circle-radius': 8, 'circle-color': '#e11d48' }"
    />
    <MaplibreNavigationControl position="top-right" />
  </MaplibreMap>
</template>
```

> [!WARNING]
> 
> MaplibreMap
> 
>  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://maplibre.mhaibaraai.cn/sitemap.md) for all pages.