Skip to content

AGENTS.md

Latest commit

 

History

History
143 lines (109 loc) · 6.2 KB

AGENTS.md

File metadata and controls

143 lines (109 loc) · 6.2 KB
Raw

CLAUDE.md

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

Project Overview

This is the React Native Mapbox Maps SDK (@rnmapbox/maps) - a community-supported library for building maps with Mapbox Maps SDK for iOS and Android in React Native applications.

Design philosophy: a thin wrapper over the native SDKs

  • @rnmapbox/maps is a low-level wrapper over the Mapbox Maps SDKs for Android and iOS. Expose APIs that mirror the upstream ones (same concepts, scope and naming), so Mapbox's docs and guides map directly onto ours.
  • Don't build clever abstractions over upstream behavior, e.g. merging two upstream mechanisms into one prop or hiding that a setting is app-wide. Many users want full control, so every upstream capability should stay reachable at that level.
  • Keep upstream scope visible: per-map features are props/methods on components, app-wide upstream settings are app-wide functions on the Mapbox module (like Mapbox.setAccessToken).
  • Convenience belongs on top, not instead: JS components, helpers or examples can streamline common cases, as long as the low-level API stays available.

Prerequisites

  • Node.js: This project requires Node.js v22.16.0 (see .nvmrc)
    • The project has been updated to use Node.js 22 with the new import syntax
    • Use nvm use to switch to the correct version

Common Development Commands

Building and Running

# Install dependencies
yarn install

# Run the example app
cd example
yarn ios  # iOS: runs on iPhone SE (3rd generation) simulator
yarn android  # Android

# Web development (experimental)
yarn web  # or: npx expo start -c --web

# Install iOS pods
yarn pod:install

Testing and Quality

# Run tests
yarn test  # Runs lint and unit tests
yarn unittest  # Just unit tests
yarn unittest:single "test name"  # Run specific test

# Code quality
yarn lint  # ESLint check
yarn lint:fix  # Auto-fix ESLint issues
yarn type:check  # TypeScript type checking

# In example app
cd example && yarn type:check

Code Generation

# IMPORTANT: Run after making changes to components or style properties
yarn generate

# This updates:
# - TypeScript definitions from style-spec
# - iOS/Android native style setters
# - Component documentation
# - Codepart replacements

Building for Different Configurations

The project uses Mapbox Maps SDK v11 and React Native's New Architecture (Fabric/TurboModules) exclusively.

Architecture Overview

Component Structure

  • Components (src/components/): React Native components that wrap native Mapbox functionality
    • Layer components: BackgroundLayer, CircleLayer, FillLayer, LineLayer, etc.
    • Source components: VectorSource, ShapeSource, RasterSource, etc.
    • Core components: MapView, Camera, UserLocation, MarkerView, PointAnnotation
    • Each component extends either AbstractLayer or AbstractSource for common functionality

Native Bridge

  • Specs (src/specs/): TurboModule/Fabric component specs
  • Native Components: Each component has corresponding native implementations:
    • iOS: ios/RNMBX/RNMBX*.swift and RNMBX*ComponentView.mm
    • Android: android/src/main/java/ (generated from specs)

Module Organization

  • location: Location management and custom location providers
  • offline: Offline map pack management and tile store
  • snapshot: Map snapshot generation

Style System

  • Styles are defined in style-spec/v8.json (Mapbox style specification)
  • TypeScript definitions generated in utils/MapboxStyles.ts
  • Native style setters generated for iOS/Android

Key Development Patterns

Adding/Modifying Components

  1. Update TypeScript component in src/components/
  2. Update or create specs in src/specs/ if needed
  3. Run yarn generate to update generated code
  4. Implement native changes if required
  5. Add example in example/src/examples/
  6. Update tests in __tests__/

Working with Styles

  • Layer styles use the Mapbox Style Specification
  • Style props are validated and converted through StyleValue utilities
  • Dynamic styles can use expressions and data-driven styling

Testing Approach

  • Unit tests use Jest with React Native preset
  • Components are tested with mocked native modules
  • Example app serves as integration testing ground
  • Use yarn test before committing

E2E / Doc Screenshots (Detox)

  • Detox tests in example/e2e/docScreenshots.e2e.js capture screenshots of every example for documentation
  • Examples with JS timers or animations that block Detox sync should set disableSync: true in their metadata
  • Examples whose screenshot isn't the same on every run (animations, label placement, random data) should set excludeFromPercy: true in their metadata to keep them out of the nightly Percy build
  • Examples that work in the web build of the example app should set webSupported: true in their metadata; their doc page then links to the example in the hosted web app (https://rnmapbox.github.io/example-app/)
  • See CONTRIBUTING.md for build and run instructions

Documentation

  • Component docs are auto-generated from JSDoc comments
  • Don't edit .md files in docs/ directly - edit source files and run yarn generate
  • Examples in example/src/examples/ are used for documentation

Fixing Bugs

  • Read and follow .github/REPRODUCING.md before writing a fix: reproduce the issue first, and verify the fix against the reproducer.
  • Make every effort to reproduce — build the example app, drive it on a simulator/device, capture logs and crash reports. Provoke bugs that don't fire on their own: tight loops, bursts, rapid create/destroy, background threads, delays/busy work, fast-failing inputs, temporary lifetime/thread instrumentation, sanitizers.
  • A reproducer is worth 100x more than a speculative fix; keep provocation code out of the final PR and attach it (with before/after evidence) to the issue/PR description instead.

Important Notes

  • Always run yarn generate after modifying components or styles
  • The example app is the primary way to test changes
  • Native changes require rebuilding the app
  • Web support is experimental and may have limited functionality
  • Requires React Native 0.79+ with New Architecture (Fabric/TurboModules)