Skip to content

MAPBOX_SETUP.md

Latest commit

 

History

History
104 lines (78 loc) · 3.38 KB

MAPBOX_SETUP.md

File metadata and controls

104 lines (78 loc) · 3.38 KB

MapBox Setup Guide

Getting Your MapBox Access Token

To use the Navigation feature, you'll need a MapBox access token. Follow these steps:

1. Create a MapBox Account

2. Get Your Access Token

  • After signing up, you'll be taken to your account page
  • Navigate to the "Access tokens" section
  • Copy your default public token, or create a new one

3. Create Environment File

  • Copy the env.example file to .env in the root directory:

    On macOS/Linux:

    cp env.example .env

    On Windows (PowerShell):

    Copy-Item env.example .env

  • Open the .env file in your editor

  • Replace your_mapbox_access_token_here with your actual token

Your .env file should look like:

VITE_MAPBOX_ACCESS_TOKEN=pk.eyJ1IjoieW91cnVzZXJuYW1lIiwiYSI6ImNsZjB4eHh4eDAwMDAwM28wMDAwMDAwMDAifQ.xxxxxxxxxxxxxxxxxxxxxxxxxxx

Important:

  • The .env file is gitignored and won't be committed to version control
  • Never commit your access token to git
  • In Vite, environment variables must be prefixed with VITE_ to be exposed to the client

4. Install Dependencies

Run the following command to install MapBox GL JS:

npm install

5. Restart Development Server

Important: After creating or modifying the .env file, you must restart the development server for the changes to take effect:

npm run dev

or

npm run electron-dev

MapBox Features

The MapBox component supports the following props:

  • center: [longitude, latitude] - Map center coordinates
  • zoom: Number (0-22) - Zoom level
  • bearing: Number (0-360) - Map rotation in degrees
  • pitch: Number (0-85) - Map tilt angle in degrees (v3 supports up to 85°)
  • style: String - MapBox style URL (defaults to streets-v12)
  • onMapLoad: Function - Callback when map finishes loading

Map Modes

The Navigation component supports both 2D and 3D map modes:

2D Maps (Default)

  • Theme-aware colors: Automatically switches between dark and light styles
  • Dark Mode: Uses mapbox://styles/mapbox/dark-v11
  • Light Mode: Uses mapbox://styles/mapbox/streets-v12
  • Flat, traditional map view optimized for navigation

3D Maps (Optional)

Enable 3D maps in Settings → Display → Map Settings to access:

  • 3D Landmark Buildings: Real 3D models of famous landmarks and buildings
  • Dynamic Lighting: Automatic shadows and lighting based on time of day
  • 3D Trees & Terrain: Enhanced visual realism
  • Theme-Aware Light Presets:
    • Dark Mode: Uses "night" preset with dark atmospheric lighting
    • Light Mode: Uses "day" preset with bright daylight
  • Uses Mapbox Standard Style (mapbox://styles/mapbox/standard)
  • Real-time Updates: Theme changes are applied instantly without reloading

The map style automatically adapts to your theme preference in both modes. When you toggle between light and dark mode, 3D maps will update their lighting in real-time to match.

Free Tier Limits

MapBox offers a generous free tier:

  • 50,000 map loads per month
  • 100,000 requests for static images
  • 50,000 directions requests
  • More than enough for personal projects!

Documentation

For more information, visit the MapBox GL JS Documentation.