# Repository: mapbox/mapbox-gl-js
# Stars: 12244

## CLAUDE.md

# CLAUDE.md

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

## Project Overview

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
- Make changes as concise as possible, ensure they are minimal and fully justified
- Read and understand relevant files before proposing code edits. If the user references a specific file/path, inspect it before explaining or proposing fixes.
- Understand WHY code exists before changing it. GL JS handles browser quirks, performance hacks, and WebGL state subtleties. Non-obvious patterns often exist for a reason—check git blame when in doubt.
- Avoid over-engineering. Only make changes that are directly requested or clearly necessary.
  - Don't add features, refactor code, or make "improvements" beyond what was asked
  - Don't create helpers or abstractions until you see repetition
  - Straightforward repetition beats unclear abstraction
- Always run `npm run tsc` and `npm run lint` when you're done making a series of code changes
- Run `npm run codegen` if you modify style properties or the style specification (regenerates style code, struct arrays, and TypeScript types)
- Run `npm run test-typings` after modifying public API types or the style specification
- Prefer running single tests, and avoid running the whole test suite, for performance
- Never add any dependencies unless explicitly requested

## Essential Commands

### Development
```bash
# 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
```bash
# 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
```bash
# Type checking
npm run tsc

# Run ESLint
npm run lint

# Run CSS linter
npm run lint-css
```

## Architecture Overview

For detailed architecture documentation including Map subsystems, SourceCache, Transform, and Controls, see [@ARCHITECTURE.md](./ARCHITECTURE.md).

### Main Thread / Worker Split

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

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

- **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

```
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

- 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

- 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

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

### Writing Unit Tests

- 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

- 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

- 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](src/shaders/README.md) for shader documentation


## README.md

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

**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](https://docs.mapbox.com/mapbox-gl-js/style-spec/), applies them to vector tiles that
conform to the [Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec), and renders them using
WebGL.

Mapbox GL JS is part of the [cross-platform Mapbox GL ecosystem](https://www.mapbox.com/maps/), which also includes
compatible native SDKs for applications on [Android](https://docs.mapbox.com/android/maps/overview/),
[iOS](https://docs.mapbox.com/ios/maps/overview/), [macOS](http://mapbox.github.io/mapbox-gl-native/macos),
[Qt](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/qt), and [React Native](https://github.com/mapbox/react-native-mapbox-gl/). 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](https://www.mapbox.com/signup/).

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](https://github.com/mapbox/mapbox-gl-native/) repository.

- [Getting started with Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/overview/)
- [Tutorials](https://docs.mapbox.com/help/tutorials/#web-apps)
- [API documentation](https://docs.mapbox.com/mapbox-gl-js/api/)
- [Examples](https://docs.mapbox.com/mapbox-gl-js/examples/)
- [Style documentation](https://docs.mapbox.com/mapbox-gl-js/style-spec/)
- [Open source styles](https://github.com/mapbox/mapbox-gl-styles)
- [Contributor documentation](./CONTRIBUTING.md)
- [Browser Data Storage](./STORAGE.md)

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

**Caption:** (_Mapbox GL JS maps, left-to-right, top-to-bottom_): Custom styled point [clusters](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#geojson-cluster), custom style with points, [hexbin visualization](https://blog.mapbox.com/exploring-nyc-open-data-with-3d-hexbins-5af2b7d8bc46) on a [Dark style](https://www.mapbox.com/maps/dark) map with [`Popups`](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup), data-driven [circles](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#circle) over a [`raster` layer](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#raster) with [satellite imagery](https://docs.mapbox.com/help/getting-started/satellite-imagery/), [3D terrain](https://docs.mapbox.com/mapbox-gl-js/example/?topic=3D) with custom [`Markers`](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker), [Mapbox Movement data](https://docs.mapbox.com/data/movement/guides/) visualization.

## License

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]