Skip to content

Documentation updates for v8 #2995

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mfedderly wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Documentation updates for v8 #2995

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a042d4
WIP readme rework around precision and supported js environments
mfedderly Jan 5, 2026
163394a
Updated per CR
mfedderly Jan 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 25 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,39 @@ Or explore the Turf API and examples at [turfjs.org](https://turfjs.org/).

## Runtime support

Turf is currently published to work with any reasonably modern Javascript runtime.
Turf is currently published to work with any reasonably modern JavaScript runtime.

Node is a first class citizen, and we recommend using an [Active or Maintenance LTS](https://nodejs.org/en/about/previous-releases) release.

Other runtimes, such as Deno or Bun, are not officially supported. We would be very interested to hear your experiences though.

## Precision

Although we make a reasonable effort for accuracy in our implementations, we are ultimately limited by the fact that we are handling GeoJSON data.
Copy link
Copy Markdown
Contributor

@bratter bratter Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would always use "precision" rather than accuracy given that the two concepts are subtly different.

For lots of consumer devices, GPS accuracy is within a few meters of the actual point. When using latitude and longitude, 6 digits after the decimal
works out to an [error around 10cm](https://datatracker.ietf.org/doc/html/rfc7946#section-11.2). Although libraries exist to provide arbitrary
precision math, we try to use JavaScript's built in numeric type (64 bit floating point) for performance reasons.
Copy link
Copy Markdown
Contributor

@bratter bratter Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider "we use JavaScript's built in types for performance reasons."

I also wonder if we could add a suggestion along the lines of: "Where operations don't depend directly on lng/lat coordinates, it is often possible to increase the effective precision on small shapes by first transforming to a zoomed in projection, running an operation, then re-projecting to lng/lat." i.e., help people understand that there are alternatives. Just a thought.


Although it is possible to specify GeoJSON positions with more than 6 digits of precision, Turf cannot guarantee correctness at these scales.
Certain operations may run into issues when the distances involved are very small, at the limit of what our Number type can represent.

We may close bugs that cannot be reproduced after the GeoJSON has been run through @turf/truncate to 6 digits.

We may return results with additional precision to avoid having to perform truncation, but that
[should not be interpreted](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.10) as the level of real precision in the result.

## Browser support

Turf uses Babel to transpile to a JavaScript version usable by most
modern browsers. Any browser that matches the following criteria as defined by [Browserslist](https://github.com/browserslist/browserslist):
@turf/turf includes a `browser` target which can be useful to load from a CDN. This uses Babel to transpile to a JavaScript version usable by most modern browsers.
This will include any browser that matches the `default` criteria as defined by [Browserslist](https://browsersl.ist/#q=defaults).
We may roll forward and drop support for older browsers within a given major release, please pin an exact version if you need to preserve specific browser compatibility.

## NPM package syntax

All of the individual @turf/* packages are written in TypeScript and are compiled to target ESNext. That means that we may use new syntax features without changing the major version.
If you have specific browser support requirements please apply Babel, SWC, or another tool in your own bundling step in order to control the amount of supporting code.

[> 0.25%, last 2 versions, fully supports es5, not dead](https://browsersl.ist/#q=%3E+0.25%25%2C+last+2+versions%2C+fully+supports+es5%2C+not+dead)
Note: Our ability to adopt the latest syntax will still be restricted by the supported Node versions for a given major version of Turf.

## Contributors

Expand Down