Overview
This document introduces Turf.js as a modular geospatial JavaScript library, covering its purpose, architecture, and organizational structure. For detailed information about individual module implementations, see Geometric Operations, Measurements and Transformations, and Spatial Analysis. For package organization and distribution details, see Package Structure.
What is Turf.js
Turf.js is a modular geospatial engine written in JavaScript for spatial analysis operations. The library provides over 100 individual modules that can be used independently or together, supporting both client-side web applications and server-side Node.js environments.
The core functionality includes:
- Geometric Operations: Buffer, intersect, union, difference operations on spatial features
- Spatial Analysis: Clustering algorithms, statistical analysis, and interpolation
- Measurements: Distance, area, bearing calculations with geodesic accuracy
- Data Utilities: GeoJSON creation, validation, and transformation helpers
- Grid Generation: Hexagonal, square, triangular, and point grid systems
Repository Architecture
Module Organization and Dependencies
The codebase follows a layered dependency architecture where higher-level modules depend on foundational utilities, but never the reverse.
Core Module Dependencies
Data Processing Pipeline
All Turf.js modules follow a consistent data flow pattern that standardizes input validation, coordinate processing, and output generation.
Standard Processing Flow
Package Distribution Strategy
Turf.js supports multiple consumption patterns through its modular architecture and build system.
| Distribution Method | Target Use Case | Entry Point | Format |
|---|---|---|---|
| Individual modules | Tree-shaking, minimal bundles | @turf/distance, @turf/buffer | ESM/CJS |
| Main package | Full functionality | @turf/turf | ESM/CJS |
| Browser bundle | Direct script inclusion | turf.min.js | UMD |
Build System Configuration
Runtime and Browser Support
Turf.js targets modern JavaScript runtimes with specific compatibility requirements. Node.js is considered a first-class citizen with support for Active and Maintenance LTS releases. Browser support follows Browserslist criteria: > 0.25%, last 2 versions, fully supports es5, not dead.
The build system uses Babel transpilation to ensure ES5 compatibility for the browser bundle, while individual modules are published with modern JavaScript features for environments that support them.