Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
146 lines (110 loc) · 4.64 KB

CONTRIBUTING.md

File metadata and controls

146 lines (110 loc) · 4.64 KB
Raw

Contributing to React Native Better Clustering

Thank you for your interest in contributing to react-native-better-clustering! This document provides guidelines and instructions for contributing to the project.

Table of Contents

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/react-native-better-clustering.git
cd react-native-better-clustering
  3. Add the upstream remote: 
    git remote add upstream https://github.com/gmi-software/react-native-better-clustering.git

Development Setup

Prerequisites

  • Node.js (v20 or higher)
  • Bun
  • React Native development environment
  • For iOS: Xcode and CocoaPods
  • For Android: Android Studio and Android SDK
  • Expo CLI (for running the example app)

Installation

# Install all workspaces (package, example, docs)
bun install

# Generate Nitro bindings (required after cloning or changing specs)
cd package
bun run specs

Running the Example App

The example app in /example is used for testing and verification:

cd example

# iOS
bunx expo prebuild
bunx expo run:ios

# Android
bunx expo prebuild
bunx expo run:android

Project Structure

react-native-better-clustering/
├── package/              # Main library package (react-native-better-clustering)
│   ├── src/              # TypeScript source
│   │   ├── compat/       # Primary MapView entry (root export)
│   │   ├── clusterer/    # Legacy render helper (undocumented subpath)
│   │   ├── engine/       # Supercluster engine bindings
│   │   ├── hooks/        # React hooks (useClusterer) — advanced subpath
│   │   ├── specs/        # Nitro Module specifications (*.nitro.ts)
│   │   └── utils/        # Shared utilities
│   ├── cpp/              # Shared C++ clustering core (ClusterEngine)
│   ├── android/          # Android native module (C++ via CMake)
│   └── nitrogen/         # Nitrogen-generated bindings
├── example/              # Expo example app
└── docs/                 # Docusaurus documentation site

Development Workflow

  • Generate Nitro bindings: cd package && bun run specs
  • Typecheck: cd package && bun run typecheck
  • Lint: cd package && bun run lint
  • Test: cd package && bun run test

Code Style

  • The project uses ESLint and Prettier. Run cd package && bun run lint before committing.
  • Keep changes scoped and avoid drive-by refactors.

Testing

  • Unit tests run with Jest: cd package && bun run test.
  • The C++ clustering core has a standalone test: 
    cd package/cpp
c++ -std=c++20 -I. ClusterEngineCore.test.cpp -o cluster_test
./cluster_test

Nitro Modules

  • Specs and types are generated by Nitrogen from *.nitro.ts files.
  • After changing any spec or Hybrid Object type, run cd package && bun run specs and commit the regenerated files under package/nitrogen/.

Pull Request Process

  1. Create a feature branch from main.
  2. Make your changes with clear, focused commits.
  3. Ensure lint, typecheck, and tests pass.
  4. Update documentation under docs/ and README.md for any public API or setup changes.
  5. Open a pull request with a clear summary, test plan, and risk notes (see AGENTS.md).

Releasing

From package/ after manual testing on iOS and Android:

bun run build
bun run test:ci
bun run release

This runs release-it (see .release-it.json): builds, tests, creates a git tag, GitHub release, and publishes to npm. Review CHANGELOG.md before releasing.

Manual test checklist (before first publish)

  • cd example && bunx expo prebuild --clean
  • bunx expo run:ios — RNBC tab renders 30k clustered markers; tap cluster zooms; pan/zoom is smooth
  • bunx expo run:android — same, with Google Maps key configured
  • Verify cluster={false} marker stays unclustered; renderCluster custom bubble shows
  • Confirm no react-native-better-clustering: errors in Metro logs
  • cd package && bun run build && bun run verify:build before bun run release