Package Structure

This document describes the organization of packages within the Turf.js codebase, their relationships, and how they form a cohesive ecosystem of geospatial functionality. For information about the core modules that form the foundation of Turf.js, see Core Modules.

Monorepo Architecture

Turf.js is organized as a monorepo using pnpm workspaces managed by Lerna, with all modules residing within the packages/ directory. The monorepo configuration is defined in lerna.json and workspace discovery is handled through pnpm-workspace.yaml.

Monorepo Management Structure

100%

Package Organization

The Turf.js ecosystem consists of the main aggregator package @turf/turf and exactly 107 individual function-specific packages as defined in the main package dependencies. Each package follows the naming convention @turf/{function-name} and provides focused geospatial operations.

Package Distribution by Category

Category	Count	Examples
Boolean Operations	12	@turf/boolean-contains, @turf/boolean-intersects, @turf/boolean-parallel
Center Calculations	5	@turf/center, @turf/center-mean, @turf/center-median, @turf/center-of-mass, @turf/centroid
Clustering	3	@turf/clusters, @turf/clusters-dbscan, @turf/clusters-kmeans
Geometric Operations	8	@turf/buffer, @turf/union, @turf/intersect, @turf/difference, @turf/dissolve
Grid Generation	4	@turf/hex-grid, @turf/square-grid, @turf/triangle-grid, @turf/point-grid
Line Operations	11	@turf/line-intersect, @turf/line-slice, @turf/line-chunk
Other Operations	58	Measurements, utilities, analysis functions
Transformations	6	@turf/transform-rotate, @turf/transform-scale, @turf/transform-translate, @turf/simplify

100%

Main Package

The @turf/turf package serves as the umbrella package that re-exports all functionality from the individual packages. It allows users to import all Turf.js functionality from a single package or selectively import specific functions.

Main Package Structure

The @turf/turf package provides multiple output formats configured through package.json exports and build scripts.

Main Package Build Pipeline

100%

Package.json Export Map Configuration:

• main: "dist/cjs/index.cjs" (CommonJS default)
• module: "dist/esm/index.js" (ES Module)
• types: "dist/esm/index.d.ts" (TypeScript types)
• browser: "turf.min.js" (UMD bundle)

Main Package Dependencies

The main package declares dependencies on all individual modules using pnpm workspace protocol notation:

"dependencies": {
  "@turf/along": "workspace:*",
  "@turf/angle": "workspace:*",
  "@turf/area": "workspace:*",
  "@turf/bbox": "workspace:*",
  "@turf/bbox-clip": "workspace:*",
  // ... 102 more workspace dependencies
  "@types/geojson": "^7946.0.10",
  "tslib": "^2.8.1"
}

The workspace:* protocol ensures that:

• All modules use the exact same version (7.2.0)
• Dependencies resolve to local packages during development
• Published versions maintain consistency across the ecosystem

Individual Packages

Each individual package follows a consistent structure designed for modern JavaScript environments.

Individual Package Structure

Each @turf/* package follows a standardized file structure and configuration pattern.

Standard Package File Structure

100%

Example: @turf/concave Package Structure

• Entry: Function concave() exported as default
• Dependencies: @turf/clone, @turf/distance, @turf/helpers, @turf/invariant, @turf/meta, @turf/tin
• External: topojson-client, topojson-server
• Test Suite: Uses tape framework with fixture-based testing

Package Export Configuration

All individual packages use identical export configuration for module system compatibility:

Dual Package Export Pattern:

{
  "type": "module",
  "main": "dist/cjs/index.cjs",
  "module": "dist/esm/index.js", 
  "types": "dist/esm/index.d.ts",
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "import": {
        "types": "./dist/esm/index.d.ts",
        "default": "./dist/esm/index.js"
      },
      "require": {
        "types": "./dist/cjs/index.d.cts", 
        "default": "./dist/cjs/index.cjs"
      }
    }
  },
  "sideEffects": false
}

Key Configuration Details:

• "type": "module": Package is ESM-first
• "sideEffects": false: Enables tree-shaking optimizations
• Conditional exports support both import and require with proper TypeScript types
• Separate type definitions for CommonJS (.d.cts) and ESM (.d.ts)

Dependency Graph

The Turf.js ecosystem follows a layered dependency structure with core utilities at the foundation.

Core Dependency Layers

100%

External Dependencies by Package Type:

• Geometric Operations: @turf/jsts (Java Topology Suite), polyclip-ts, d3-geo
• Spatial Analysis: rbush (spatial indexing), concaveman, topojson-*
• Grid/Interpolation: marchingsquares (contour generation)

Module Categories

The Turf.js packages can be categorized by their functionality:

Category	Description	Example Packages
Core Utilities	Fundamental utilities for creating, manipulating, and validating GeoJSON	@turf/helpers, @turf/meta, @turf/invariant
Boolean Operations	Functions that evaluate spatial relationships	@turf/boolean-contains, @turf/boolean-intersects
Geometric Operations	Functions that generate new geometries	@turf/buffer, @turf/union, @turf/intersect
Measurements	Functions for calculating spatial measurements	@turf/distance, @turf/area, @turf/bearing
Transformations	Functions that transform geometries	@turf/transform-rotate, @turf/simplify
Line Operations	Functions specific to linestrings	@turf/line-slice, @turf/line-intersect
Spatial Analysis	Advanced analytical operations	@turf/clusters-kmeans, @turf/voronoi
Grids & Interpolation	Functions for generating grids and interpolation	@turf/hex-grid, @turf/isolines

Build System

Turf.js employs a dual-build system using TSUP for individual packages and Rollup for the UMD bundle.

Build Tool Configuration

100%

Build Script Patterns:

Standard package build:

"scripts": {
  "build": "tsup --config ../../tsup.config.ts",
  "test": "npm-run-all --npm-path npm test:*",
  "test:tape": "tsx test.ts"
}

Main package build (additional Rollup step):

"scripts": {
  "build": "tsup --config ../../tsup.config.ts && rollup -c rollup.config.js",
  "last-checks": "npm-run-all last-checks:testjs last-checks:example"
}

Rollup UMD Configuration:

• Input: index.ts (aggregated exports)
• Output: turf.min.js with global name turf
• Plugins: CommonJS, Node resolve, Babel, Terser (minification)

Build Configuration

The build process is configured through several files:

1. tsup.config.ts (shared across packages)
2. rollup.config.js (for UMD bundle in main package)
3. nx.json (for build caching and dependencies)

Each package defines its build scripts in its package.json:

"scripts": {
  "build": "tsup --config ../../tsup.config.ts",
  "test": "npm-run-all --npm-path npm test:*",
  "test:tape": "tsx test.ts"
}

The main package additionally includes a Rollup configuration for generating the UMD bundle:

"scripts": {
  "build": "tsup --config ../../tsup.config.ts && rollup -c rollup.config.js"
}

Version Management

All Turf.js packages share the same version number, managed through Lerna:

{
  "$schema": "node_modules/lerna/schemas/lerna-schema.json",
  "npmClient": "pnpm",
  "version": "7.2.0",
  "command": {
    "publish": {
      "registry": "https://registry.npmjs.org"
    }
  }
}

This ensures that all packages are released together with consistent versioning.

Package Import Patterns

Users can choose between importing the entire library or individual functions:

Full Library Import

// Import entire library (UMD build)
import * as turf from '@turf/turf';
turf.distance(point1, point2);

// Or in CommonJS
const turf = require('@turf/turf');
turf.distance(point1, point2);

Individual Function Import

// Import specific functions (smaller bundle size)
import { point } from '@turf/helpers';
import distance from '@turf/distance';

// Or in CommonJS
const distance = require('@turf/distance').default;
const { point } = require('@turf/helpers');

Summary

The Turf.js package structure follows a modular design pattern with:

1. A main package (@turf/turf) that serves as an aggregator of all functionality
2. Individual function-specific packages with standardized structure and exports
3. Core utility packages that provide fundamental functionality
4. Specialized packages for various geospatial operations
5. A shared build configuration using modern JavaScript tooling
6. Consistent versioning across all packages

This architecture provides flexibility for users to choose between importing the entire library or only the specific functions they need, while maintaining a cohesive development experience within the project.