Development Guide

This document provides an overview of the development workflow, tooling, and processes for contributing to Turf.js. It covers local environment setup, quality tooling, testing infrastructure, documentation generation, and the continuous integration/deployment pipeline.

For detailed information about contributing code and submitting pull requests, see Contributing. For specifics about the build system and compilation process, see Build System. For the complete release workflow and versioning process, see Release Process.

Development Workflow Overview

The Turf.js development workflow follows a standard fork-and-pull-request model with automated quality checks and continuous integration. The workflow progresses from local development through automated testing to eventual release.

100%

Local Environment Setup

Prerequisites

Requirement	Version/Details
Node.js	Active or Maintenance LTS (18.x, 20.x, or 22.x)
Package Manager	pnpm (via corepack or global install)
Git	Latest stable version

Installation Steps

The local setup process is straightforward:

1. Enable pnpm (Node 16+):

   corepack enable pnpm

   Alternatively, install globally: npm install -g pnpm

2. Clone and install:

   git clone https://github.com/Turfjs/turf.git
   cd turf
   pnpm install

3. Verify setup:

   pnpm test

The pnpm install command installs all dependencies and runs the prepare script, which executes husky && lerna run build to set up git hooks and build all packages.

Quality Tooling Architecture

Turf.js employs a comprehensive suite of automated quality tools to ensure code consistency, correctness, and maintainability across 100+ packages.

100%

Quality Tool Details

Tool	Purpose	Configuration	Execution
ESLint	JavaScript/TypeScript linting	@eslint/js, typescript-eslint	pnpm lint:eslint or pre-commit
Prettier	Code formatting	.prettierrc	prettier --write on staged files
TypeScript	Type checking	tsconfig.json per package	During build and type tests
Monorepolint	Package consistency	.monorepolint.config.mjs	mrl check in CI
Husky	Git hooks	.husky/pre-commit	Automatic on git commit
lint-staged	Staged file processing	package.json:18-29	Via Husky hook

The lint-staged configuration automatically processes files before commit:

• Runs mrl check --paths on package.json files
• Runs eslint --fix on all *.js and *.ts files
• Regenerates documentation for modified index.{js,ts} files
• Formats all files with prettier --write --ignore-unknown

Testing Infrastructure

Turf.js uses a multi-layered testing strategy to validate functionality, types, and performance across all packages.

Test Types and Execution

100%

Test Organization

Each package follows a standard test structure:

• Unit Tests: Located in test.ts files, using the tape testing framework
• Type Tests: Located in types.ts files, validated by TypeScript compiler with strict settings
• Performance Tests: Located in bench.ts files, using the benchmark library
• Fixture Tests: GeoJSON input files in test/in/ directory, expected outputs in test/out/

The package-level test script uses npm-run-all to execute all test:* scripts in parallel, typically including test:tape and optionally test:types.

Documentation Generation

Turf.js documentation is automatically generated from JSDoc comments in source code, ensuring API documentation stays synchronized with implementation.

100%

Documentation Workflow

The documentation generation process is managed by the generate-readmes.ts script:

Execution Context	Command	Scope
Single package	pnpm run docs (in package dir)	Current package only
All packages	pnpm run docs (in root)	All packages
Automatic	git commit	Modified packages only

The script extracts JSDoc comments from index.ts or index.js files and generates markdown README files. These README files should never be manually edited - all changes must be made to the JSDoc comments in source files.

The lint-staged configuration ensures that when a package's index.{js,ts} file is modified and staged, the README is automatically regenerated before commit.

Continuous Integration Pipeline

Turf.js uses GitHub Actions to automate testing, building, and publishing across multiple Node.js versions and deployment scenarios.

CI/CD Workflows

100%

Workflow Details

Build Workflow (turf.yml)

• Triggers: Push or pull request to master or support/6.x branches
• Matrix: Tests across Node.js 18.x, 20.x, and 22.x
• Steps: Checkout → Setup pnpm → Setup Node with cache → Install dependencies → Verify no changes → Run tests
• Purpose: Validates all changes work across supported Node versions

Prerelease Workflow (prerelease.yml)

• Triggers: Push to master branch (disabled by default)
• Environment: Node 18.x, Ubuntu latest
• Command: lerna publish minor --canary --include-merged-tags --force-publish --dist-tag prerelease --ignore-scripts true --yes
• Output: Publishes alpha version to npm with format 7.x.x-alpha.N where N is commits since last release
• Purpose: Enables testing of unreleased changes in real environments

Release Workflow (release.yml)

• Triggers: Push of version tags matching v*.*.* pattern
• Environment: Node 18.x, Ubuntu latest
• Command: lerna publish from-package --ignore-scripts true --yes
• Artifacts: Publishes to npm registry and creates draft GitHub release with auto-generated notes
• Purpose: Automates official releases from version tags

Package Manager and Monorepo Management

Turf.js uses pnpm as its package manager and lerna for monorepo orchestration, with strict enforcement through monorepolint.

Tool Configuration

Tool	Version/Config	Purpose
pnpm	10.10.0 (via packageManager field)	Workspace dependency management
lerna	^8.2.2	Package versioning and publishing
monorepolint	0.5.0	Package.json consistency enforcement

The preinstall script enforces pnpm usage:

"preinstall": "npx only-allow pnpm"

The prepare script ensures packages are built after installation:

"prepare": "husky && lerna run build"

Monorepolint Rules

The .monorepolint.config.mjs configuration enforces consistency across all packages:

• Package field order: Standardized ordering of fields in package.json files
• Alphabetical sorting: Dependencies and scripts sorted alphabetically
• Required entries: Ensures all packages have correct type, main, module, types, exports fields
• Script templates: Enforces standard scripts like build, test, docs, bench
• Dependency requirements: Mandates specific dev dependencies (tape, tsup, tsx) for TypeScript packages

The configuration dynamically discovers packages by scanning the packages/turf-* directory and categorizes them based on file presence (.ts vs .js files, test files, benchmark files).