Repository: mapbox/mapbox-gl-js

Stars: 12244

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview Copy Chapter

Mapbox GL JS is a JavaScript library for interactive, customizable vector maps on the web. It uses WebGL to render vector tiles that conform to the Mapbox Vector Tile Specification.

Workflow Copy Chapter

Essential Commands Copy Chapter

Development Copy Section

Start development server with live reload

npm run start
Build development version

npm run build-dev
Build production bundles

npm run build-prod-min  # Minified production build
npm run build-css       # Build CSS file
Generate code (style code, struct arrays, and TypeScript types)

npm run codegen

Testing Copy Section

Test TypeScript definitions

npm run test-typings
Run unit tests

npm run test-unit
Run unit tests for specific file

npm run test-unit -- test/unit/style-spec/spec.test.ts
Run specific test inside a file (use -t with test name pattern)

npm run test-unit -- test/unit/style/style.test.ts -t 'Style#addImage'
Run render tests with pattern matching

npm run test-render -- -t "render-tests/background-color"

Code Quality Copy Section

Type checking

npm run tsc
Run ESLint

npm run lint
Run CSS linter

npm run lint-css

Architecture Overview Copy Chapter

For detailed architecture documentation including Map subsystems, SourceCache, Transform, and Controls, see @ARCHITECTURE.md.

Main Thread / Worker Split Copy Section

Mapbox GL JS uses WebWorkers to parse vector tiles off the main thread:

1. Main Thread: Handles rendering, user interactions, and map state
2. Worker Threads: Parse vector tiles, perform layout operations, and prepare render-ready data

Rendering Pipeline Copy Section

1. Tile Fetching & Parsing (Worker)
- Vector tiles are fetched and deserialized from PBF format
- Features are transformed into render-ready WebGL buffers
- Feature geometries are indexed for spatial queries

2. Layout Process (Worker)
- WorkerTile#parse() creates Bucket instances for style layer families
- Each Bucket holds vertex and element array data for WebGL rendering
- ProgramConfiguration handles shader attribute/uniform configuration

3. WebGL Rendering (Main Thread)
- Rendering happens layer-by-layer in Painter#render(), Painter.renderPass tracks the current render phase
- Layer-specific draw() methods in src/render/draw_.js
- Shader programs are compiled and cached by Painter

Key Components Copy Section

- Map: Central class managing the map instance
- Style: Manages map styling and layer configuration
- SourceCache: Manages tile loading and caching
- Transform: Handles map positioning and projections
- Painter: WebGL rendering orchestration

Project Structure Copy Chapter

3d-style/          # 3D building and model rendering
src/
├── data/          # Data structures for tiles and rendering
├── geo/           # Geographic calculations and transformations
├── gl/            # WebGL abstraction layer
├── render/        # Rendering implementation
├── shaders/       # GLSL shaders with custom #pragma directives
├── source/        # Tile source implementations
├── style/         # Style layer implementations
├── style-spec/    # Mapbox Style Specification (separate workspace)
├── symbol/        # Text and icon rendering
├── terrain/       # 3D terrain rendering
├── ui/            # User interaction handlers
└── util/          # Utility functions
test/
├── unit/          # Unit tests (Vitest)
├── integration/   # Integration and render tests
└── build/         # Build-related tests

Code Style Copy Chapter

- ES6+ features are used throughout
- Prefer immutable data structures
- Always use named exports, default exports are forbidden
- Modules export classes or functions (no namespace objects)
- JSDoc comments for all public APIs
- Don't use !. for non-null assertions (hides potential null issues)
- Don't use ?. or ?? operators (hides null handling, harder to debug)
- Use assert for invariants
- Break complex expressions into named variables, especially WebGL math

TypeScript Copy Chapter

- The project has TypeScript configured with strict: false, but write all TypeScript code as if strict mode is enabled
- This means: always handle null/undefined cases, use proper type annotations, avoid any types, and ensure type safety

Testing Guidelines Copy Chapter

- Tests use Vitest framework with Playwright for testing in browsers
- Install Playwright browsers: npx playwright install chromium

Writing Unit Tests Copy Section

- No shared variables between test cases
- Don't mock internal domain objects (Style, Map, Transform, Dispatcher)
- One return value or side effect per test - pull shared logic into functions
- Only test return values and global side effects - not internal behavior or method calls
- No network requests - use mockFetch from test/util/network.ts if needed
- Use clear input space partitioning - look for edge cases

Documentation Conventions Copy Chapter

- All public API must have JSDoc comments; private items tagged with @private
- Use markdown in JSDoc; surround code identifiers with \backticks\
- Class descriptions: describe what the class/instances are (e.g., "A layer that...")
- Function descriptions: start with third-person verb (e.g., "Sets...", "Returns...")
- For functions returning values, start with "Returns..."
- Event descriptions: start with "Fired when..."

WebGL and Shaders Copy Chapter

- Custom #pragma mapbox directives in shaders expand to uniforms or attributes
- Shader programs are dynamically generated based on style properties
- Data-driven styling creates paint vertex arrays at layout time
- See @src/shaders/README.md for shader documentation

README.md Copy Chapter

<img width="300" alt="Mapbox logo" src="https://static-assets.mapbox.com/logos/mapbox-logo-black.png">

Mapbox GL JS is a JavaScript library for interactive, customizable vector maps on the web. It takes map styles that conform to the
Mapbox Style Specification, applies them to vector tiles that
conform to the Mapbox Vector Tile Specification, and renders them using
WebGL.

Mapbox GL JS is part of the cross-platform Mapbox GL ecosystem, which also includes
compatible native SDKs for applications on Android,
iOS, macOS,
Qt, and React Native. Mapbox provides building blocks to add location features like maps, search, and navigation into any experience you
create. To get started with GL JS or any of our other building blocks,
sign up for a Mapbox account.

In addition to GL JS, this repository contains code, issues, and test fixtures that are common to both GL JS and the
native SDKs. For code and issues specific to the native SDKs, see the
mapbox/mapbox-gl-native repository.

- Getting started with Mapbox GL JS
- Tutorials
- API documentation
- Examples
- Style documentation
- Open source styles
- Contributor documentation
- Browser Data Storage

<img width="600" alt="Mapbox GL JS gallery of map images" src="https://static-assets.mapbox.com/images/mapbox-gl-js-gallery.png">

Caption: (_Mapbox GL JS maps, left-to-right, top-to-bottom_): Custom styled point clusters, custom style with points, hexbin visualization on a Dark style map with Popups, data-driven circles over a raster layer with satellite imagery, 3D terrain with custom Markers, Mapbox Movement data visualization.

License Copy Chapter

Mapbox Web SDK

Copyright © 2021 - 2023 Mapbox, Inc. All rights reserved.

The software and files in this repository (collectively, “Software”) are licensed under the Mapbox TOS for use only with the relevant Mapbox product(s) listed at www.mapbox.com/pricing. This license allows developers with a current active Mapbox account to use and modify the authorized portions of the Software as needed for use only with the relevant Mapbox product(s) through their Mapbox account in accordance with the Mapbox TOS. This license terminates automatically if a developer no longer has a Mapbox account in good standing or breaches the Mapbox TOS. For the license terms, please see the Mapbox TOS at https://www.mapbox.com/legal/tos/ which incorporates the Mapbox Product Terms at www.mapbox.com/legal/service-terms. If this Software is a SDK, modifications that change or interfere with marked portions of the code related to billing, accounting, or data collection are not authorized and the SDK sends limited de-identified location and usage data which is used in accordance with the Mapbox TOS. [Updated 2023-01]