mapbox-web-integration-patterns
π―Skillfrom mapbox/mapbox-agent-skills
|Provides official, production-ready integration patterns for embedding Mapbox GL JS across web frameworks with best practices and setup guidance.
Part of
mapbox/mapbox-agent-skills(9 items)
Installation
npx add-skill mapbox/mapbox-agent-skillsnpx add-skill mapbox/mapbox-agent-skills --skill mapbox-web-performance-patternsnpx add-skill mapbox/mapbox-agent-skills --listnpx add-skill mapbox/mapbox-agent-skills -a cursornpx add-skill mapbox/mapbox-agent-skills -a vscode+ 2 more commands
Skill Details
Official integration patterns for Mapbox GL JS across popular web frameworks. Covers setup, lifecycle management, token handling, search integration, and common pitfalls. Based on Mapbox's create-web-app scaffolding tool.
Token Management Patterns
Environment Variables (Recommended)
Different frameworks use different prefixes for client-side environment variables:
| Framework/Bundler | Environment Variable | Access Pattern |
| -------------------- | ------------------------------- | ------------------------------------------ |
| Vite | VITE_MAPBOX_ACCESS_TOKEN | import.meta.env.VITE_MAPBOX_ACCESS_TOKEN |
| Next.js | NEXT_PUBLIC_MAPBOX_TOKEN | process.env.NEXT_PUBLIC_MAPBOX_TOKEN |
| Create React App | REACT_APP_MAPBOX_TOKEN | process.env.REACT_APP_MAPBOX_TOKEN |
| Angular | environment.mapboxAccessToken | Environment files (environment.ts) |
Vite .env file:
```bash
VITE_MAPBOX_ACCESS_TOKEN=pk.YOUR_MAPBOX_TOKEN_HERE
```
Next.js .env.local file:
```bash
NEXT_PUBLIC_MAPBOX_TOKEN=pk.YOUR_MAPBOX_TOKEN_HERE
```
Important:
- β Always use environment variables for tokens
- β
Never commit
.envfiles to version control - β Use public tokens (pk.\*) for client-side apps
- β
Add
.envto.gitignore - β
Provide
.env.exampletemplate for team
.gitignore:
```
.env
.env.local
.env.*.local
```
.env.example:
```bash
VITE_MAPBOX_ACCESS_TOKEN=your_token_here
```
---
Mapbox Search JS Integration
Search Box Component Pattern
Install dependency:
```bash
npm install @mapbox/search-js-react # React
npm install @mapbox/search-js-web # Vanilla/Vue/Svelte
```
Note: Both packages include @mapbox/search-js-core as a dependency. You only need to install -core directly if building a custom search UI.
React Search Pattern:
```jsx
import { SearchBox } from '@mapbox/search-js-react';
// Inside component:
accessToken={accessToken}
map={mapRef.current} // Pass map instance
mapboxgl={mapboxgl} // Pass mapboxgl library
value={inputValue}
onChange={(value) => setInputValue(value)}
proximity={centerCoordinates} // Bias results near center
marker // Show marker for selected result
/>;
```
Key configuration options:
accessToken: Your Mapbox public tokenmap: Map instance (must be initialized first)mapboxgl: The mapboxgl library referenceproximity:[lng, lat]to bias results geographicallymarker: Boolean to show/hide result markerplaceholder: Search box placeholder text
Positioning Search Box
Absolute positioning (overlay):
```jsx
style={{
position: 'absolute',
top: 10,
right: 10,
zIndex: 10,
width: 300
}}
>
```
Common positions:
- Top-right:
top: 10px, right: 10px - Top-left:
top: 10px, left: 10px - Bottom-left:
bottom: 10px, left: 10px
---
Common Mistakes to Avoid
β Mistake 1: Forgetting to call map.remove()
```javascript
// BAD - Memory leak!
useEffect(() => {
const map = new mapboxgl.Map({ ... })
// No cleanup function
}, [])
```
```javascript
// GOOD - Proper cleanup
useEffect(() => {
const map = new mapboxgl.Map({ ... })
return () => map.remove() // β Cleanup
}, [])
```
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
```javascript
// BAD - Infinite loop in React!
function MapComponent() {
const map = new mapboxgl.Map({ ... }) // Runs on every render
return
}
```
```javascript
// GOOD - Initialize in effect
function MapComponent() {
useEffect(() => {
const map = new mapboxgl.Map({ ... })
}, [])
return
}
```
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
```javascript
// BAD - map variable lost between renders
function MapComponent() {
useEffect(() => {
let map = new mapboxgl.Map({ ... })
// map variable is not accessible later
}, [])
}
```
```javascript
// GOOD - Store in useRef
function MapComponent() {
const mapRef = useRef()
useEffect(() => {
mapRef.current = new mapboxgl.Map({ ... })
// mapRef.current accessible throughout component
}, [])
}
```
Why: You need to access the map instance for operations like adding layers, markers, or calling remove().
---
β Mistake 4: Wrong dependency array in useEffect
```javascript
// BAD - Re-creates map on every render
useEffect(() => {
const map = new mapboxgl.Map({ ... })
return () => map.remove()
}) // No dependency array
// BAD - Re-creates map when props change
useEffect(() => {
const map = new mapboxgl.Map({ center: props.center, ... })
return () => map.remove()
}, [props.center])
```
```javascript
// GOOD - Initialize once
useEffect(() => {
const map = new mapboxgl.Map({ ... })
return () => map.remove()
}, []) // Empty array = run once
// GOOD - Update map property instead
useEffect(() => {
if (mapRef.current) {
mapRef.current.setCenter(props.center)
}
}, [props.center])
```
Why: Map initialization is expensive. Initialize once, then use map methods to update properties.
---
β Mistake 5: Hardcoding token in source code
```javascript
// BAD - Token exposed in source code
mapboxgl.accessToken = 'pk.YOUR_MAPBOX_TOKEN_HERE';
```
```javascript
// GOOD - Use environment variable
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
```
Why: Tokens in source code get committed to version control and exposed publicly. Always use environment variables.
---
β Mistake 6: Not handling Angular SSR
```typescript
// BAD - Crashes during server-side rendering
ngOnInit() {
import('mapbox-gl').then(mapboxgl => {
this.map = new mapboxgl.Map({ ... })
})
}
```
```typescript
// GOOD - Check platform first
ngOnInit() {
if (!isPlatformBrowser(this.platformId)) {
return // Skip map init during SSR
}
import('mapbox-gl').then(mapboxgl => {
this.map = new mapboxgl.Map({ ... })
})
}
```
Why: Mapbox GL JS requires browser APIs (WebGL, Canvas). Angular Universal (SSR) will crash without platform check.
---
β Mistake 7: Missing CSS import
```javascript
// BAD - Map renders but looks broken
import mapboxgl from 'mapbox-gl';
// Missing CSS import
```
```javascript
// GOOD - Import CSS for proper styling
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';
```
Why: The CSS file contains critical styles for map controls, popups, and markers. Without it, the map appears broken.
---
Next.js Specific Patterns
App Router (Recommended)
```typescript
'use client' // Mark as client component
import { useRef, useEffect } from 'react'
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'
export default function Map() {
const mapRef = useRef
const mapContainerRef = useRef
useEffect(() => {
if (!mapContainerRef.current) return
mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_TOKEN!
mapRef.current = new mapboxgl.Map({
container: mapContainerRef.current,
center: [-71.05953, 42.36290],
zoom: 13
})
return () => mapRef.current?.remove()
}, [])
return
}
```
Key points:
- Must use
'use client'directive (maps require browser APIs) - Use
process.env.NEXT_PUBLIC_*for environment variables - Type
mapRefproperly with TypeScript
Pages Router (Legacy)
```typescript
import dynamic from 'next/dynamic'
// Dynamically import to disable SSR for map component
const Map = dynamic(() => import('../components/Map'), {
ssr: false,
loading: () => Loading map...
})
export default function HomePage() {
return
}
```
Key points:
- Use
dynamicimport withssr: false - Provide loading state
- Map component itself follows standard React pattern
---
Style Configuration
Default Center and Zoom Guidelines
Recommended defaults:
- Center:
[-71.05953, 42.36290](Boston, MA) - Mapbox HQ - Zoom:
13for city-level view
Zoom level guide:
0-2: World view3-5: Continent/country6-9: Region/state10-12: City view13-15: Neighborhood16-18: Street level19-22: Building level
Customizing for user location:
```javascript
// Use browser geolocation
if (navigator.geolocation) {
navigator.geolocation.getCurrentPosition((position) => {
map.setCenter([position.coords.longitude, position.coords.latitude]);
map.setZoom(13);
});
}
```
---
Testing Patterns
Unit Testing Maps
Mock mapbox-gl:
```javascript
// vitest.config.js or jest.config.js
export default {
setupFiles: ['./test/setup.js']
};
```
```javascript
// test/setup.js
vi.mock('mapbox-gl', () => ({
default: {
Map: vi.fn(() => ({
on: vi.fn(),
remove: vi.fn(),
setCenter: vi.fn(),
setZoom: vi.fn()
})),
accessToken: ''
}
}));
```
Why: Mapbox GL JS requires WebGL and browser APIs that don't exist in test environments. Mock the library to test component logic.
---
When to Use This Skill
Invoke this skill when:
- Setting up Mapbox GL JS in a new project
- Integrating Mapbox into a specific framework
- 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 GL JS Documentation](https://docs.mapbox.com/mapbox-gl-js/)
- [Mapbox Search JS Documentation](https://docs.mapbox.com/mapbox-search-js/)
- [create-web-app GitHub](https://github.com/mapbox/create-web-app)
More from this repository8
Optimizes Mapbox web applications by eliminating initialization waterfalls, reducing load times, and improving rendering performance across data loading and map rendering.
Provides curated Mapbox style patterns and layer configurations for implementing common mapping use cases like restaurant finders, real estate, and data visualization.
Validates and optimizes Mapbox styles by checking expressions, accessibility, data integrity, and performance before production deployment.
Secures Mapbox access tokens by implementing granular scope management, URL restrictions, and token rotation strategies across different environments.
Guides map designers in creating visually compelling and accessible Mapbox maps using expert cartographic principles, color theory, and typography best practices.
Provides robust, lifecycle-aware Mapbox Maps SDK integration patterns for Android using Kotlin and Jetpack Compose.
Enables seamless Mapbox Maps SDK integration in iOS apps using Swift, SwiftUI, and UIKit with best practices for lifecycle management and performance.
Helps developers seamlessly migrate from Google Maps Platform to Mapbox GL JS by providing comprehensive API translation, styling patterns, and migration strategies.