Installation

This guide provides detailed instructions for installing and configuring MapboxGL.

Requirements

• Node.js 16.0 or higher
• Modern browsers (Chrome, Firefox, Safari, Edge)

Installation Methods

Method 1: Using Package Managers

npm

npm install mapbox-gl

yarn

yarn add mapbox-gl

pnpm

pnpm add mapbox-gl

Method 2: Using CDN

<!-- Mapbox GL JS -->
<script src="https://cdn.jsdelivr.net/npm/mapbox-gl@3.7.0/dist/mapbox-gl.min.js"></script>

<!-- Mapbox GL CSS -->
<link href="https://cdn.jsdelivr.net/npm/mapbox-gl@3.7.0/dist/mapbox-gl.min.css" rel="stylesheet">

Using in Projects

Vite Project

// main.js or main.ts
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

// Set access token
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN

export { mapboxgl }

// .env
VITE_MAPBOX_TOKEN=your_access_token_here

Vue 3 Project

<template>
  <div id="map" ref="mapContainer"></div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

const mapContainer = ref(null)

onMounted(() => {
  const map = new mapboxgl.Map({
    container: mapContainer.value,
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [116.3974, 39.9093],
    zoom: 11
  })
})
</script>

<style scoped>
#map {
  width: 100%;
  height: 100vh;
}
</style>

React Project

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

mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN'

function Map() {
  const mapContainer = useRef(null)
  const map = useRef(null)

  useEffect(() => {
    if (map.current) return

    map.current = new mapboxgl.Map({
      container: mapContainer.current,
      style: 'mapbox://styles/mapbox/streets-v12',
      center: [116.3974, 39.9093],
      zoom: 11
    })

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

  return <div ref={mapContainer} style={{ width: '100%', height: '100vh' }} />
}

export default Map

Development Tools

TypeScript Type Definitions

npm install @types/mapbox-gl --save-dev

Vue Development Tools

If you use Vue, it's recommended to install official MapboxGL Vue components:

npm install @studiometa/vue-mapbox-gl
# or
npm install v-mapbox

Performance Tips

Performance Optimization

1. Use latest version of MapboxGL
2. Configure preserveDrawingBuffer option appropriately
3. For large datasets, consider using data clustering
4. Use WebGL 2.0 for better performance

Troubleshooting

Issue: Map not displaying

Solution:

1. Check if access token is valid
2. Ensure container element has explicit height and width
3. Check browser console for error messages

Issue: Style loading failure

Solution:

1. Ensure CSS file is properly imported
2. Check if style URL is correct
3. Verify network connection

Issue: TypeScript type errors

Solution:

npm install @types/mapbox-gl --save-dev

Or add to tsconfig.json:

{
  "compilerOptions": {
    "types": ["mapbox-gl"]
  }
}