RFC: Node support, browser support

[Josh-Cena]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

I'm recently thinking about what qualifies as a breaking change (also mentioned in #6113). But not exactly API breaking changes, but environment support.

For example, we unintentionally dropped support for Node versions below 14.13, which didn't support statically analyzing some named export patterns in ESM, causing our import {program} from 'commander'; in create-docusaurus to fail. The solution to that was simple: we specified the version requirement to a minor (#7271).

The support for ESM is constant-improving, and it's almost impossible to confidently say "we support Node v14+" unless we make sure that every code path works in Node v14.0. This will be a huge problem for #6520 in the long term. In addition, there are some libraries like [email protected] that specifically require Node v14.15+ — what do we do in this case for people on a minor below 14.15?

In general I don't think it's very hard to issue an error and ask people to bump their Node to a higher minor version, but it will be a breaking change nevertheless, if we agree that "any change that prevents a site from building is a breaking change". However, how do we actually know? Do we always run Node tests on the lowest permitted version?

My proposal is to support the latest minor version of maintenance LTS and active LTS (which often contain backported features from the current version), and all versions of the "current" release. We probably won't use a lot of shiny new features, but it will unblock us from doing certain meaningful things.

On the other hand, there's also the issue of browser support. JavaScript APIs suffer less in this aspect because most of them remain polyfillable/transpilable, although we did fall into a few pitfalls in the past (e.g. #3680). CSS is a more prominent issue. We recently used a few new CSS features in Infima (e.g. facebookincubator/infima#246) for good will, but browser support doesn't even cross 90%. CSS is not polyfillable. Should we do this?

An easy answer is we support the default browser query (>0.5%, not dead, not op_mini all), but do note that this includes IE 11 as well (although it soon won't). Would it be reasonable to say "the last three major versions of Chrome and Firefox, and the last three minor versions of Safari"? This will impact every site visitor of a particular site, not just the site creators themselves. This is also the reason why we are conservative at using APIs like scroll-behavior.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[slorber]

TLDR of my Node.js opinion:

• 2.0 should be released with >= 16.x ("active".x at 2.0 release time) and preserve support in every 2.x
• 3.0.alpha should start dev using >= "current"

---

Current table:

Older Node.js bump issues:

• Bumping to Node 12: chore(v2): upgrade dependencies + require Node 12 #4223
• Bumping to Node 14: chore: require Node 14 #5812
• Bumping to Node 16: chore: require Node 16.14 #7501

When we bumped to Node.js 14, v12 was still in LTS maintenance and v14 was the active version.

If we were to formalize the Node upgrade strategy, what about requiring at least the active version, and removing support for LTS maintenance asap?

Not sure about minor, major versions, but maybe we could have node: ['16.0', '16, '18.0', '18']

---

Regarding major Docusaurus releases

2.0 is not officially out so doing a breaking change on this is not a big deal. We currently mark PRs as breaking changes for convenience, but in practice, everything is a breaking change compared to v1.0 😅

2.0 is not officially out, so doing a breaking change on the Node version is actually not really one. Of course, it can be annoying for users if we do this but it shouldn't be forbidden.

Soon, we'll be doing Docusaurus major releases more regularly.

We could commit to avoiding BC in the beta or RC phase 🤷‍♂️

Once GA released, we should not do BC so if 2.0 is released with Node.js 16.0 support, it will stay on that version forever. Now if we release with >= 16.4.2, that's also fine to keep it. 2.x will be mostly for bugfixes and easy to backport features, not for major deps upgrades.

Now, I'm perfectly fine if we decide to be a bit more aggressive on bumping the Node.js version of the "next version" of Docusaurus (which is 2.0 currently). For example, if we release 2.0 today and then start working on 3.0, and we need to use a very recent version of Node.js for some ambitious reasons, let's bump aggressively in v3.0

---

Browser env

That's a whole different story that should rather have its own issue.

We don't have a very good infra to check our effective browser support in practice 🤪 and browserslist will not solve everything.

Agree that we were a bit optimistic merging those newer CSS features, although they will probably have much better support before we have a better way to test for all this 😅

[slorber]

We bumped to Node.16.14 here: #7501

16.14 instead of 16.0 because we want to use some features that are not in 16.0, like Error Cause

To formalize this: when we are about to release a new major Docusaurus version, let's use $current.x at release time, where x may be >= 0 if we want to use some specific Node.js features asap.

[rainecheck]

NodeJS 16 EOL is being brought forward to Sep 11: https://nodejs.org/en/blog/announcements/nodejs16-eol

[slorber]

Yes!
We'll drop support for Node 16 in Docusaurus v3

---

Something to consider when changing the Node version number is that hosts may not support newer Node versions yet.

For example, Node.js 20 is not yet supported by Vercel, so it would be odd if Docusaurus v3 required Node.js 20 to run.

And Vercel in turns probably can't support Node.js 20 until AWS add support (they use the same node version for build and serverless functions)

Let's see what was the timeline for Node 18 adoption:

• v18 LTS start: 2022-10-25
• v18 AWS support: 2022-11-18 (https://aws.amazon.com/fr/about-aws/whats-new/2022/11/aws-lambda-support-node-js-18/)
• v18 Vercel support: 2022-11-18 (https://vercel.com/changelog/node-js-18-lts-is-now-available)