Установка и подключение

Turf.js представляет собой модульную библиотеку для геопространственных вычислений в JavaScript-экосистеме. Она распространяется как набор независимых функций, которые подключаются по отдельности или целиком, в зависимости от выбранного способа интеграции.

Наиболее распространённый способ подключения в современных JavaScript-проектах основан на пакетных менеджерах Node.js. Библиотека публикуется в npm-реестре и устанавливается стандартной командой:

npm install @turf/turf

После установки пакет становится доступен в node_modules, а зависимости автоматически фиксируются в package.json.

Использование в коде:

import * as turf from "@turf/turf";

const point = turf.point([30.5, 50.5]);
const buffered = turf.buffer(point, 10, { units: "kilometers" });

Такой способ подключения загружает весь набор функций библиотеки. Это удобно на этапе разработки или при небольших проектах, где размер бандла не является критичным фактором.

Подключение отдельных модулей

Архитектура Turf.js основана на принципе tree-shaking: каждая геофункция существует как отдельный пакет. Это позволяет подключать только необходимые части.

Пример установки конкретной функции:

npm install @turf/buffer

Использование:

import buffer from "@turf/buffer";
import point from "@turf/point";

const center = point([10, 10]);
const area = buffer(center, 5, { units: "miles" });

Такой подход уменьшает итоговый размер сборки и повышает производительность в браузерных приложениях.

Подключение через CDN

Для использования в браузере без сборщика доступна загрузка через CDN. Подключение осуществляется через глобальный объект:

<script src="https://cdn.jsdelivr.net/npm/@turf/turf@latest/turf.min.js"></script>

После загрузки библиотека становится доступна через глобальную переменную:

const point = turf.point([40, 55]);
const distance = turf.distance(
  turf.point([40, 55]),
  turf.point([41, 56]),
  { units: "kilometers" }
);

CDN-вариант сохраняет простоту интеграции, но не предоставляет механизмов оптимизации размера бандла.

Использование в ES Modules

В современных фронтенд-стеков (Vite, Snowpack, Webpack, Rollup) предпочтительным считается использование ES Modules.

import distance from "@turf/distance";
import point from "@turf/point";

const from = point([0, 0]);
const to = point([1, 1]);

const result = distance(from, to, { units: "kilometers" });

Сборщики автоматически выполняют tree-shaking, исключая неиспользуемый код.

Подключение в CommonJS

В проектах, использующих Node.js без ESM, применяется CommonJS-синтаксис:

const turf = require("@turf/turf");

const pt = turf.point([12, 14]);
const area = turf.circle(pt, 10, { units: "kilometers" });

Несмотря на поддержку, такой подход постепенно уступает место ES Modules, особенно в новых проектах.

Подключение в браузерных сборках

При работе с Webpack или аналогичными сборщиками важно учитывать оптимизацию импорта. Полная загрузка пакета может приводить к избыточному размеру итогового файла.

Пример конфигурации:

import centroid from "@turf/centroid";
import polygon from "@turf/helpers";

const poly = polygon([
  [
    [0, 0],
    [10, 0],
    [10, 10],
    [0, 10],
    [0, 0]
  ]
]);

const center = centroid(poly);

В таких конфигурациях сборщик анализирует зависимости и исключает неиспользуемые части библиотеки.

Подключение в TypeScript-проектах

Turf.js включает встроенную поддержку TypeScript-типов, что позволяет использовать строгую типизацию без дополнительных пакетов.

Пример:

import point from "@turf/point";
import { Feature, Point } from "geojson";

const p: Feature<Point> = point([25, 60]);

Типы обеспечивают контроль структуры GeoJSON-объектов и снижают вероятность ошибок при работе с координатами.

Работа в Node.js окружении

В серверных приложениях Turf.js используется для геообработки данных, анализа расстояний, построения зон и обработки GeoJSON.

import bbox from "@turf/bbox";
import polygon from "@turf/helpers";

const poly = polygon([
  [
    [0, 0],
    [20, 0],
    [20, 20],
    [0, 20],
    [0, 0]
  ]
]);

const bounds = bbox(poly);

Node.js не требует дополнительных настроек, так как Turf.js не зависит от DOM или браузерных API.

Особенности работы с модулями

Каждая функция Turf.js реализована как чистая функция без состояния. Это влияет на способ подключения:

  • отсутствуют глобальные зависимости между модулями
  • каждый пакет может использоваться автономно
  • нет необходимости инициализации библиотеки
  • возможна агрегация функций на уровне сборщика

Такой дизайн позволяет гибко комбинировать функциональность.

Структура пакетов

Экосистема построена вокруг пакета @turf/turf, который агрегирует отдельные модули:

  • @turf/helpers — создание GeoJSON-объектов
  • @turf/buffer — построение буферных зон
  • @turf/distance — вычисление расстояний
  • @turf/area — расчёт площади
  • @turf/intersect — пересечение геометрий

Каждый модуль имеет минимальные зависимости и может использоваться независимо.

Подключение в монорепозиториях

В монорепозиториях (Nx, Turborepo, Lerna) Turf.js устанавливается на уровне отдельных пакетов или корневого workspace.

Пример структуры:

packages/
  map-app/
  geo-service/
node_modules/

В каждом пакете могут использоваться разные наборы Turf-функций, что снижает избыточность зависимостей.

Оптимизация загрузки

При работе с большими картографическими приложениями критичным становится размер итогового бандла. Использование точечных импортов позволяет уменьшить нагрузку:

import simplify from "@turf/simplify";

В отличие от:

import * as turf from "@turf/turf";

Первый вариант предпочтителен в production-сборках.

Совместимость версий

Turf.js развивается как набор независимых пакетов с синхронизированными версиями. При обновлении важно учитывать:

  • совместимость между модулями одного релиза
  • изменения в структуре GeoJSON
  • обновления алгоритмов вычислений

Несовпадение версий отдельных пакетов может привести к расхождениям в результатах геоопераций.

Итоговая модель интеграции

Механизм подключения Turf.js строится вокруг трёх основных сценариев:

  • полная загрузка библиотеки через агрегированный пакет
  • модульное подключение отдельных функций
  • подключение через CDN без сборки

Каждый сценарий соответствует разным уровням контроля над производительностью, размером кода и архитектурой приложения.

Оглавление