Mapbox Integration Patterns Skill

This skill provides official patterns for integrating Mapbox GL JS into web applications using React, Vue, Svelte, Angular, and vanilla JavaScript. These patterns are based on Mapbox's create-web-app scaffolding tool and represent production-ready best practices.

Version Requirements

Mapbox GL JS

Recommended: v3.x (latest)

- Minimum: v3.0.0
Why v3.x: Modern API, improved performance, active development
v2.x: Legacy; no longer actively developed (see migration notes below)

Installing via npm (recommended for production):

CODEBLOCK0

CDN (for prototyping only):

CODEBLOCK1

Framework Requirements

React: GL JS works with React 16.8+ (requires hooks). create-web-app scaffolds with React 19.x.
Vue: GL JS works with Vue 2.x+ (Vue 3 Composition API recommended).
Svelte: GL JS works with any Svelte version. create-web-app scaffolds with Svelte 5.x.
Angular: GL JS works with Angular 2+. create-web-app scaffolds with Angular 19.x.
Next.js: Minimum 13.x (App Router), Pages Router 12.x+.

Mapbox Search JS

CODEBLOCK2

Version Migration Notes (v2.x to v3.x)

- WebGL 2 now required
INLINECODE4 option removed
Improved TypeScript types, better tree-shaking support
No breaking changes to core initialization patterns

Token patterns (work in v2.x and v3.x):

CODEBLOCK3

Core Principles

Every Mapbox GL JS integration must:

1. Initialize the map in the correct lifecycle hook
Store map instance in component state (not recreate on every render)
Always call map.remove() on cleanup to prevent memory leaks
Handle token management securely (environment variables)
Import CSS: INLINECODE6

React Integration (Primary Pattern)

Pattern: useRef + useEffect with cleanup

Note: These examples use Vite (the bundler used in create-web-app). If using Create React App, replace import.meta.env.VITE_MAPBOX_ACCESS_TOKEN with process.env.REACT_APP_MAPBOX_TOKEN. See Token Management Patterns for other bundlers.

CODEBLOCK4

Key points:

- Use useRef for both map instance and container
Initialize in useEffect with empty deps INLINECODE12
Always return cleanup function that calls INLINECODE13
Never initialize map in render (causes infinite loops)

React + Search JS

CODEBLOCK5

Search JS Integration Summary

Install:

CODEBLOCK6

Both packages include @mapbox/search-js-core as a dependency. Only install -core directly if building a custom search UI.

Key configuration options:

- accessToken: Your Mapbox public token
INLINECODE17: Map instance (must be initialized first)
INLINECODE18: The mapboxgl library reference
INLINECODE19: [lng, lat] to bias results geographically
INLINECODE21: Boolean to show/hide result marker
INLINECODE22: Search box placeholder text

Positioning Search Box

Absolute positioning (overlay):

CODEBLOCK7

Common positions:

- Top-right: INLINECODE23
Top-left: INLINECODE24
Bottom-left: INLINECODE25

Common Mistakes (Critical)

Mistake 1: Forgetting to call map.remove()

CODEBLOCK8

Why: Every Map instance creates WebGL contexts, event listeners, and DOM nodes. Without cleanup, these accumulate and cause memory leaks.

Mistake 2: Initializing map in render

CODEBLOCK9

Why: React components re-render frequently. Creating a new map on every render causes infinite loops and crashes.

Mistake 3: Not storing map instance properly

CODEBLOCK10

Why: You need to access the map instance for operations like adding layers, markers, or calling remove().

Mistake 4: Storing map instance in Vue's data() (Vue-specific)

CODEBLOCK11

Why: In Vue (especially Vue 3), data() properties are wrapped in a Proxy for reactivity. Mapbox GL JS internally checks object identity and uses properties that don't survive proxy wrapping. Storing the map in data() causes subtle, hard-to-debug failures. Instead, assign the map instance directly as this.map in mounted() — properties assigned outside data() are not made reactive.

Reference Files

Load these for framework-specific patterns and additional details:

- references/vue.md — Vue Integration (mounted/unmounted lifecycle)
INLINECODE34 — Svelte Integration (onMount/onDestroy)
INLINECODE35 — Angular Integration with SSR handling
INLINECODE36 — Vanilla JS (Vite) + Vanilla JS (CDN)
INLINECODE37 — Web Components (basic + reactive + usage in React/Vue/Svelte)
INLINECODE38 — Next.js App Router + Pages Router
INLINECODE39 — Common Mistakes 4-7 + Testing Patterns
INLINECODE40 — Token Management per bundler + Style Configuration

When to Use This Skill

Invoke this skill when:

- Setting up Mapbox GL JS in a new project
Integrating Mapbox into a specific framework (React, Vue, Svelte, Angular, Next.js)
Building framework-agnostic Web Components
Creating reusable map components for component libraries
Debugging map initialization issues
Adding Mapbox Search functionality
Implementing proper cleanup and lifecycle management
Converting between frameworks (e.g., React to Vue)
Reviewing code for Mapbox integration best practices

Related Skills

- mapbox-cartography: Map design principles and styling
mapbox-token-security: Token management and security
mapbox-style-patterns: Common map style patterns

Resources

Mapbox 集成模式技能

本技能提供了使用 React、Vue、Svelte、Angular 和原生 JavaScript 将 Mapbox GL JS 集成到 Web 应用程序中的官方模式。这些模式基于 Mapbox 的 create-web-app 脚手架工具，代表了生产环境就绪的最佳实践。

版本要求

Mapbox GL JS

推荐版本： v3.x（最新版）

- 最低版本： v3.0.0
为何选择 v3.x： 现代化 API、性能提升、持续开发中
v2.x： 遗留版本；不再积极开发（参见下方迁移说明）

通过 npm 安装（推荐用于生产环境）：

bash
npm install mapbox-gl@^3.0.0 # 安装最新的 v3.x 版本

CDN（仅用于原型开发）：

html

框架要求

React： GL JS 支持 React 16.8+（需要 hooks）。create-web-app 使用 React 19.x 进行脚手架搭建。
Vue： GL JS 支持 Vue 2.x+（推荐使用 Vue 3 组合式 API）。
Svelte： GL JS 支持任何 Svelte 版本。create-web-app 使用 Svelte 5.x 进行脚手架搭建。
Angular： GL JS 支持 Angular 2+。create-web-app 使用 Angular 19.x 进行脚手架搭建。
Next.js： 最低 13.x（App Router），Pages Router 12.x+。

Mapbox Search JS

bash
npm install @mapbox/search-js-react@^1.0.0 # React
npm install @mapbox/search-js-web@^1.0.0 # 其他框架

版本迁移说明（v2.x 到 v3.x）

- 现在需要 WebGL 2
移除了 optimizeForTerrain 选项
改进了 TypeScript 类型，更好的 tree-shaking 支持
核心初始化模式没有破坏性变更

令牌模式（适用于 v2.x 和 v3.x）：

javascript
const token = import.meta.env.VITEMAPBOXACCESS_TOKEN; // 在生产环境中使用环境变量

// 全局令牌（自 v1.x 起可用）
mapboxgl.accessToken = token;
const map = new mapboxgl.Map({ container: ... });

// 每个地图的令牌（多地图设置时推荐）
const map = new mapboxgl.Map({
accessToken: token,
container: ...
});

核心原则

每个 Mapbox GL JS 集成必须：

1. 在正确的生命周期钩子中初始化地图
将地图实例存储在组件状态中（不在每次渲染时重新创建）
始终在清理时调用 map.remove() 以防止内存泄漏
安全地处理令牌管理（环境变量）
导入 CSS：import mapbox-gl/dist/mapbox-gl.css

React 集成（主要模式）

模式：useRef + useEffect 带清理

注意： 这些示例使用 Vite（create-web-app 中使用的打包工具）。如果使用 Create React App，请将 import.meta.env.VITEMAPBOXACCESSTOKEN 替换为 process.env.REACTAPPMAPBOXTOKEN。其他打包工具请参见令牌管理模式。

jsx
import { useRef, useEffect } from react;
import mapboxgl from mapbox-gl;
import mapbox-gl/dist/mapbox-gl.css;

function MapComponent() {
const mapRef = useRef(null); // 存储地图实例
const mapContainerRef = useRef(null); // 存储 DOM 引用

useEffect(() => {
mapboxgl.accessToken = import.meta.env.VITEMAPBOXACCESS_TOKEN;

mapRef.current = new mapboxgl.Map({
container: mapContainerRef.current,
center: [-71.05953, 42.3629],
zoom: 13
});

// 关键：清理以防止内存泄漏
return () => {
mapRef.current.remove();
};
}, []); // 空依赖数组 = 挂载时运行一次

return

;
}

关键点：

- 对地图实例和容器都使用 useRef
在带有空依赖 [] 的 useEffect 中初始化
始终返回调用 map.remove() 的清理函数
绝不在渲染中初始化地图（会导致无限循环）

React + Search JS

jsx
import { useRef, useEffect, useState } from react;
import mapboxgl from mapbox-gl;
import { SearchBox } from @mapbox/search-js-react;
import mapbox-gl/dist/mapbox-gl.css;

const accessToken = import.meta.env.VITEMAPBOXACCESS_TOKEN;
const center = [-71.05953, 42.3629];

function MapWithSearch() {
const mapRef = useRef(null);
const mapContainerRef = useRef(null);
const [inputValue, setInputValue] = useState();

useEffect(() => {
mapboxgl.accessToken = accessToken;

mapRef.current = new mapboxgl.Map({
container: mapContainerRef.current,
center: center,
zoom: 13
});

return () => {
mapRef.current.remove();
};
}, []);

return (
<>
style={{
margin: 10px 10px 0 0,
width: 300,
right: 0,
top: 0,
position: absolute,
zIndex: 10
}}
>
accessToken={accessToken}
map={mapRef.current}
mapboxgl={mapboxgl}
value={inputValue}
proximity={center}
onChange={(d) => setInputValue(d)}
marker
/>

);
}

Search JS 集成总结

安装：

bash
npm install @mapbox/search-js-react # React
npm install @mapbox/search-js-web # 原生/Vue/Svelte

两个包都包含 @mapbox/search-js-core 作为依赖项。只有在构建自定义搜索 UI 时才直接安装 -core。

关键配置选项：

- accessToken：您的 Mapbox 公共令牌
map：地图实例（必须首先初始化）
mapboxgl：mapboxgl 库引用
proximity：[lng, lat] 用于按地理位置偏向结果
marker：布尔值，显示/隐藏结果标记
placeholder：搜索框占位文本

定位搜索框

绝对定位（覆盖层）：

jsx
style={{
position: absolute,
top: 10,
right: 10,
zIndex: 10,
width: 300
}}

常见位置：

- 右上角：top: 10px, right: 10px
左上角：top: 10px, left: 10px
左下角：bottom: 10px, left: 10px

常见错误（关键）

错误 1：忘记调用 map.remove()

javascript
// 错误 - 内存泄漏！
useEffect(() => {
const map = new mapboxgl.Map({ ... })
// 没有清理函数
}, [])

// 正确 - 正确清理
useEffect(() => {
const map = new mapboxgl.Map({ ... })
return () => map.remove() // 清理
}, [])

原因： 每个 Map 实例都会创建 WebGL 上下文、事件监听器和 DOM 节点。没有清理，这些会累积并导致内存泄漏。

错误 2：在渲染中初始化地图

javascript
// 错误 - React 中无限循环！
function MapComponent() {
const map = new mapboxgl.Map({ ... }) // 每次渲染都运行
return

}

// 正确 - 在 effect 中初始化
function MapComponent() {
useEffect(() => {
const map = new mapboxgl.Map({ ... })
}, [])
return

}

原因： React 组件

mapbox-web-integration-patternsMapbox网页集成模式

mapbox-web-integration-patterns

Mapbox Integration Patterns Skill

Version Requirements

Mapbox GL JS

Framework Requirements

Mapbox Search JS

Version Migration Notes (v2.x to v3.x)

Core Principles

React Integration (Primary Pattern)

React + Search JS

Search JS Integration Summary

Positioning Search Box

Common Mistakes (Critical)

Mistake 1: Forgetting to call map.remove()

Mistake 2: Initializing map in render

Mistake 3: Not storing map instance properly

Mistake 4: Storing map instance in Vue's data() (Vue-specific)

Reference Files

When to Use This Skill

Related Skills

Resources

Mapbox 集成模式技能

版本要求

Mapbox GL JS

框架要求

Mapbox Search JS

版本迁移说明（v2.x 到 v3.x）

核心原则

React 集成（主要模式）

React + Search JS

Search JS 集成总结

定位搜索框

常见错误（关键）

错误 1：忘记调用 map.remove()

错误 2：在渲染中初始化地图

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement