Update the transpilation targets of the various packages

[mfedderly]

The next time we make a major version change, I'd propose that we make the following changes around platform support.

All packages will ship "main" and "module" targets that can potentially use any syntax. We will change TypeScript to target esnext, and reserve the right to roll forward to any new syntax supported by TypeScript at any time even without a major release of Turf itself. Our own CI will still limit us from introducing syntax newer than the Nodejs versions in our support matrix.

For @turf/turf, there is an additional "browser" target, where we currently transpile with Babel. Currently that is set to use "targets": "> 0.25%, last 2 versions, fully supports es5, not dead". I propose that we change that instead to "targets": "since 2024-01-01", which gives us browser support for anything released in the last 2 years or so, but forces less transpilation including the important jump to es6 syntax.

In our CI we should drop any unsupported Node versions, and remove them from official support in the library as well.

We can also drop all of the escheck guarding, since we are shipping esnext syntax instead (and turf.min.js would be guarded by Babel anyhow).

The outcomes here would be:

• Turf webapp consumers must transpile @turf/* packages in their bundling process for their own browser targets
• Bundles being created are as small as possible with the newest possible syntax
• target: "esnext" and erasableSyntaxOnly: true implies that we can removeimportHelpers: true and tslib dependencies (I think)
• turf.min.js can use much more modern syntax, but nothing too recent. Interestingly this doesn't seem to save much overall space in the final bundle, which is still largely dominated by @turf/jsts.

[mfedderly]

On a related note, there's a similar discussion to be had about removing commonjs exports at all from the packages. It would let us drop the tsup wrapper and go back to native TypeScript for the build step. I'm not convinced that we should do that in the next major, but I'm open to being convinced.

[planted-mreinstein]

removing commonjs exports at all from the packages

This, 1000%. All major browsers and all supported versions of node and bun and deno all natively support ESM. The node community in general is being too safe with this, we should stop bringing legacy baggage along with us from last decade.

[mfedderly]

@planted-mreinstein do you have examples of other libraries that are dropping commonjs exports entirely already? I've seen a few, but if we had some other examples to point to, I'd feel better about more eagerly removing it. We've been talking about dropping tsup since it has been deprecated, and shipping both esm/cjs comes with some (manageable) complexity that I'd rather do away with instead if we can justify it.

cc @smallsaucepan who was looking at the tsup thing.

[planted-mreinstein]

do you have examples of other libraries

All of my libraries do not ship with commonjs any more, and haven't for years. Though I'm not a popular github star, by any stretch of imagination. :-D All of Sindre's modules have moved to pure esm a while ago and there doesn't seem to be any impact in terms of using them: https://github.com/sindresorhus

I'd feel better about more eagerly removing it

I would pose a counter question, who actually needs commonjs? The first version of node to support esm by default is v12.18, which released almost 7 years ago. That is so far out of support. All of the browsers support esm now: https://caniuse.com/es6-module typescript, babel, esbuild, etc. all support es modules.

We've been talking about dropping tsup since it has been deprecated

Yes, please just do that. :-D This is the big benefit of semver; make turf@8 esm only, and ideally limit other breaking changes in version 8. Most users will be able to upgrade with no issue, and it won't hurt anyone on any pre-existing versions of turf.

Most of your users are not on node v12 and if they are they are not on the upgrade treadmill and aren't going to adopt turf@next anyway.

and shipping both esm/cjs comes with some (manageable) complexity that I'd rather do away with instead if we can justify it

Yeah I mean this is part of what is holding back node and js generally. Our tools can't thin out legacy crap that we needed from 10 years ago because we're all following node org's lead and being too conservative in my not so humble opinion. :)

[planted-mreinstein]

This was no less true 3 years ago when this article was written, and it's even more so now as support has only increased since then: https://deno.com/blog/commonjs-is-hurting-javascript

[smallsaucepan]

I'd be as happy as anyone to remove cruft from Turf. However, I don't think we really know what our users are running on or with, and would recommend not ditching CJS just because we don't know anyone who uses it.

As a bit of a counterpoint https://bun.sh/blog/commonjs-is-not-going-away Not agreeing or disagreeing with any particular point of difference. Just noting neither option is a slam dunk.

The updated npm stats from that article are below. Plain ESM has doubled, while dual packaged has 20x-ed.

I accept that's more reflective of library author sentiment than user need. And probably better tools like tsup becoming available. However it's certainly not saying we're in a minority either.

Semver might technically allow us to make any breaking change we want. At the same time though we do want to try to keep as many people on currently maintained versions and avoid eroding any good will Turf has built up.

So, is there a way to find out what our users actually use? Do we do a poll? Parse the package.json files of our top 1000 dependants? None will be perfect, though I'd like to see us go to some effort first.

[planted-mreinstein]

is there a way to find out what our users actually use?

https://www.npmjs.com/package/@turf/turf?activeTab=versions

Do we do a poll? Parse the package.json files of our top 1000 dependants?

I suspect a community vote is impractical given the insane maintenance abandon rate of npm module owners. I'm also skeptical that we're going to run a thoughtful and time consuming survey project here just to decide whether it makes sense to modernize turf's imports, but maybe I'm overly cynical. That just feels like a roundabout way of saying "maybe" and putting it off forever.

Plain ESM has doubled, while dual packaged has 20x-ed.

All that metric provides is how many packages have followed node org's lead. I don't think it's a good indicator of what turf should do. Most people don't exercise or eat well, and if we looked at survey numbers for that, we shouldn't take those results as an indication of "good" behavior. :)

At the same time though we do want to try to keep as many people on currently maintained versions

Not arguing against that. What I am saying is anyone that is going to bother updating to turf@8 is not going to be on a node version older than 12.18, for the most part. You're not alienating your users because it's a self selecting group of people who upgrade. If people stay on whatever version they're on it will continue to work in perpetuity. If they decide to update, they're already going to be using a compatible node env.

[mfedderly]

It looks like Leaflet is moving to esm only in their current master branch for 2.0 beta. Thats the sort of precedent I’d be willing to follow and move to esm only.

Overall my feeling is that it’s a real but minor annoyance for us to ship cjs and esm correctly. With monorepolint to push the package.json changes through, it’ll only really live in one place.

It won’t motivate users to fix their own esm support if we do both, but other than the duplicate bytes it also isn’t really costing them much for us to ship both. I don’t really believe anyone needs cjs shipped, but kicking the decision down the road another year also seems pretty cheap.

[planted-mreinstein]

It won’t motivate users to fix their own esm support if we do both

I don't think there's anything for users to fix, is there? As long as they are using node 12.18 or higher there shouldn't be any impact to any dependents of turf, or it's direct users.

but kicking the decision down the road another year also seems pretty cheap

Agreed it's not the end of world if you wait a year, but I don't understand what will change a year from now either. Why is that the magic number that makes the anxiety about removing cjs go away? Is it just watching what happens with leaflet, and if their world doesn't explode, turf follows the same course? Can you folks produce an esm-only beta? That seems similarly safe?

[smallsaucepan]

That just feels like a roundabout way of saying "maybe" and putting it off forever

We've only just met @planted-mreinstein so you'll have to take me at my word that "asking if there's a way to make an informed decision" is not avoidance 😉

Without a pressing need that benefits our users, I don't understand the drive to do this. Especially given it's trivial for us to continue to provide the capability.

Agree that at some point all these libraries will need to make the break. It would be a stretch though to conclude all 87% of those currently supporting CJS are living in a dreamland.

I would not support dropping CJS without at least trying to engage with our users to understand their situations. If they choose not to take part, fine that's on them. At least we tried.

anyone that is going to bother updating to turf@8 is not going to be on a node version older than 12.18 ... If they decide to update, they're already going to be using a compatible node env
...
I don't think there's anything for users to fix, is there? As long as they are using node 12.18 or higher there shouldn't be any impact to any dependents of turf, or it's direct users

Quick sidebar to make sure we're on the same page. Using node 12.18 or higher doesn't automatically make commonjs client code able to import ESM. The runtime can run both, but the import-ability between package types is not bi-directional. If someone uses require() in their application and we only ship ESM they won't be able to use that version of Turf without changing their environment or using workarounds.

Apologies if I've misunderstood what you were getting at here though.

[planted-mreinstein]

You'll have to take me at my word that "asking if there's a way to make an informed decision" is not avoidance

Fair enough. :) Nice to meet you by the way 👋 Thanks for all of your work on turf, it's been a lifesaver in several projects!

Making informed decisions are a good thing generally, I'm not trying to rush anyone through a process or take away thoughtful consideration.

I think taking a poll on the surface sounds like a good idea, but if we were to dive deeper into that, there are a lot of thorny questions that come up:

• how many people would actually respond, would it be a large enough sample size?
• is there a selection bias, that a certain archetype of developer that is more open to participating in polls also skews towards voting a certain way?
• what's the criteria for making a decision to proceed with eliminating cjs, does it have to unanimous or is it a simple majority, or 2/3 majority?
• does the vote enable people to make more subtle distinctions in their vote beyond yes / no ?

These are just the ones I can think of off the cuff. I'm sure if we wanted to do some kind of poll/vote we could, and I'm not opposed to that. It'd probably be interesting just on a meta level of seeing what happens when a popular js module tries to solicit feedback. Also probably a lot of work. :) I think it would generate a lot of talk and there would still be the same anxiety about the change.

Without a pressing need that benefits our users, I don't understand the drive to do this.

Using let and const block-scoped variables don't help turf users in any direct way. But we still adopt these things because we perceive them to make development more tolerable. The other drive (for me anyway) is seeing the ecosystem move forward. A lot of people lament that web development is a dumpster fire, and part of that is overly complicated build systems, and still packaging up solutions to problems that just about every environment has solved for natively. So part of it is I'd like to see some kind of shedding of this baggage, because it just make things lighter and better for everyone.

the import-ability between package types is not bi-directional. If someone uses require() in their application and we only ship ESM they won't be able to use that version of Turf without changing their environment or using workarounds

You’re right that require() consumers can’t use an ESM-only major without changing something. But that’s exactly what a major version is for. You can ship v8 as ESM-only, and CJS users simply remain on v7. If you want to be extra responsible, you can maintain v7 with bug/security fixes for a period and document the migration steps. I don't know this for a fact but I suspect that people still on codebases using require in their apps are not keeping up to date with deps, and are likely rocking some pretty old module versions. What you do in v8 onwards is not likely going to matter for the vast majority of people on those codebases because they are likely being kept running on versions that even precede the current v7. They tend to be in maintenance mode and people don't want to touch them with a 10m stick. :-D. At least that tends to be the pattern I've seen.

[mfedderly]

Perhaps another principled date we could use is waiting until the end of Node 20 official support, as Node 22 added the flag that lets you require() esm. That would be like April/June 2026.