node, browser bundles, esm, cjs, and all that stuff

[smallsaucepan]

Before v7 release is it worth working through the environments we want Turf to be compatible in? Node and browser, ESM and CJS, etc. There might be some old build artefacts we can remove now given how much typescript, rollup, etc have progressed in the last four or five years.

Any pain points you know of or suggestions where to start?

[mfedderly]

For node runtimes, I think we should probably only officially support nodejs versions that are still support from nodejs itself. Right now I think that's 21, 20, and 18. I think that lets us use a typescript target of es2022 and import/export syntax for modules.

If we take that and run it through caniuse for browser support, you get a slightly worse story (scroll down to the Feature Summary section). Safari got support for its last feature pretty late (in 2023) which feels a little uncomfortable. es2021 is a bit better. That probably gets us enough browser support that anyone consuming our modules directly into their bundles is unlikely to need to transpile our code?

We might also just take the standpoint that if you're consuming our stuff, we target esnext and you should transpile them to your desired browser support. I know how to accomplish this in a bundling step, but perhaps its too large of a barrier to impose on our consumers who may be less familiar with how to set this sort of thing up.

Separately, we have a browser target for @turfjs/turf, we could potentially pick an even earlier target to provide better compatibility across the board for that file.

[smallsaucepan]

Thanks @mfedderly . Summarising all the dimensions to help keep track:

Ecmascript target version: Do we want to stick with something even older than es2021? es2017 for example would let Svelte, React Native, and a few others use us without needing to further transpile. Unless we need new language features, we should go with the oldest target possible yes?

turf-min browser target: same as the above

node module resolution: We could make it esnext (currently node16) though what happens when esnext recalibrates to point to something newer? Lock it at node16?

ESM first: From what I understand we currently take a "CJS first" approach. Modules are assumed to contain commonjs except for the /dist/es directory where we plonk a {"type":"module"} package.json

We could potentially tidy this up by switching to an ESM first approach, and using the .cjs file extension to identify the legacy commonjs parts? So we would go from:

/package.json <---- cjs implied from project root
  /dist/es
    /index.js <---- esm
    /package.json <---- this directory esm
  /dist/js
    /index.js <---- cjs
    /index.d.ts <---- types, potentially used by esm and cjs consumers

To this:

/package.json <---- type: "module" to indicate esm within
  /dist
    /index.d.ts <---- types
    /index.js <---- esm
    /index.cjs <---- ALWAYS cjs

Then those three entry points are listed in the module package.json. Sure to be some wrinkles around export code from old 3rd party libraries. The above seems like it would work and be simpler in the majority of cases.

[twelch]

I don't have enough hands-on experience with this to give definitive thoughts, but I am for this being worked through and will closely follow and offer what I can.

From what I can tell, you are suggesting that for the ESM-first approach, both ESM and CJS builds will still be offered in the build? I understand this can be a challenge. A specific article comes to mind from Mark Erikson, a maintainer of redux and friends, which also uses rollup and typescript -- https://www.reddit.com/r/reactjs/comments/15ljbhq/my_experience_modernizing_the_redux_packages_to/

[smallsaucepan]

That's a really helpful link thanks Tim. Yep still would expect to offer both types. Some things I hadn't come across before e.g. forgetting about having a "type" and using mjs and cjs extensions explicitly, and removing default exports (adding named exports in next PR so halfway there for that).

Having a bunch of little test apps was something I figured we'd have to do, though including them in CI is next level.

Most of this is new to me as well, at least from the publisher side of things. I'm hopeful we won't have as many problems as the redux suite given most turf modules are stateless, and don't have to integrate closely with React. Where we might run into issues is leveraging / re-packaging third party libs, especially old JS that we're tracking locally.

I'm not suggesting we change for change's sake. Feels like the time is right though - ecosystem continues to shift, and our v7 is coming up. With some engagement with the alphas happening as well that's probably the release phase to pull a switch like this.

[smallsaucepan]

Going to retire our two rollup-plugins also. Can't see where either of them are used any more:

• valid-es5.js - reference removed from rollup config a few years back
• typescript-export.js - still in rollup config but generated code doesn't seem to contain "module.exports" anywhere. This might have been quietly fixed by a typescript version upgrade somewhere along the line

[mfedderly]

valid-es5 got replaced by es-check
Sounds good about typescript-export, there's a chance that consumers are just smarter about looking for things at .default now that ESM are more broadly adopted.

[mfedderly]

I'm open to any level of ecmascript target version, preferably as high as we think we can reasonably make it given consumer needs.
For moduleResolution I'm definitely more comfortable with node16 over esnext, just for future's sake. Anything we can do to avoid it being node will help 😬

[smallsaucepan]

PR #2555 created as a result of this discussion and #2400 🎉

Thanks for all your thoughts.