Describe current Site integration issues with CRA 5 in documentation

[userzimmermann]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

https://mdxjs.com/docs/getting-started/#create-react-app-cra states that: "There is no need to configure it."

Unfortunately, that's currently not the case with CRA 5 anymore; and many people (including myself) have already spent a lot of time with figuring out reasons & finding workarounds …

Solution

Please add a statement to https://mdxjs.com/docs/getting-started/#create-react-app-cra —briefly describing the situation & maybe directing people to possible workarounds like those discussed in #1870

Alternatives

Just accepting the situation and waiting for facebook/create-react-app#12166 to get fixed …

[wooorm]

Sounds like you have the insights needed to document this? Are you perhaps interested in contributing?

[userzimmermann]

Ok, @wooorm – If you direct me to the corresponding documentation sources, then I'll add it :)

[wooorm]

At the bottom of each page on the website is a link “Edit this page on GitHub”, that points you to the file you want to edit. More on how to contribute is explained in the contribution guide: https://mdxjs.com/community/contribute/.

[userzimmermann]

Good morning, @wooorm :) & first: Thanks for quickly merging #2007 —yet I still can't build the documentation locally:

$ npm run docs-generate

> docs-generate
> cross-env NODE_LOADER_CONFIG=website/loader-react-server.js node --unhandled-rejections=strict --no-warnings --experimental-loader @node-loader/core --conditions=react-server website/generate.server.js

file:///C:/Users/userz/Projects/mdx/docs/_component/layout.server.js:56
      <div>
      ^

SyntaxError: Unexpected token '<'
    at ESMLoader.moduleStrategy (node:internal/modules/esm/translators:139:18)
    at ESMLoader.moduleProvider (node:internal/modules/esm/loader:236:14)

JSX syntax is not accepted in .js files; which sounds reasonable ;) —but somehow it must work for you (and your CI) … Am I missing some Node.js environment setting to enable this general JSX support? Is this Windows-related?

And—a maybe blasphemous question ;D —why not using .jsx file endings?

[wooorm]

Use Node 14.

Unfortunately Vercel only supports Node 14 currently.
Experimental node loaders changed between v14 and v17+, but we can’t update to the fix because Vercel is stuck on an old Node version.

why not using .jsx file endings?

That would not solve the problem here. The problem isn’t which files are loaded. The problem is that custom loaders (e.g., JSX or MDX -> JS) don’t work.

[userzimmermann]

Use Node 14.

Which wonderfully works!—& as a side-effect I'm now familiar with NVM!—& #2009 tears down my final contribution barrier :)

[echarles]

I hit the same issue while generating the docs site with node 18 and indeed node 14 solves it.

1. Should an engine key be added to package.json to inform developers of that constraint?
2. Does that mean that the whole MDX library ecosystem do no work with node >14?

[wooorm]

Are you talking about CRA, per this issue, or about the docs of this project?

Re 1: No, this is about the docs site
Re 2: No, MDX can as far as I am aware even be used on Node 10, with some experimental esm flag

[echarles]

Are you talking about CRA, per this issue, or about the docs of this project?

talking about the docs with npm run docs - Sorry I just realize that the issue is about CRA, so may not be the best place to discuss...

Re 1: No, this is about the docs site

yep, so if the docs can only be built with Node 14, engines key could be added https://docs.npmjs.com/cli/v9/configuring-npm/package-json#engines

Re 2: No, MDX can as far as I am aware even be used on Node 10, with some experimental esm flag

Is that documented somewhere?

[remcohaszing]

yep, so if the docs can only be built with Node 14, engines key could be added https://docs.npmjs.com/cli/v9/configuring-npm/package-json#engines

Adding engines would cause npm install to fail for the mono repo for other Node.js versions.

Is that documented somewhere?

Yes, it’s docmented for every package, e.g.: https://mdxjs.com/packages/mdx/#install

[wooorm]

For how to build the site, see the contribution docs: https://mdxjs.com/community/contribute/#site

Is that documented somewhere?

The recommendation in the docs is to use a maintained version of Node. That is Node 14 currently. End of the month that will be Node 16: https://github.com/nodejs/Release.
All docs currently mention 12, because Node 10 needed a flag, and you should be at 14+ anyway.

[echarles]

Agree, engines is not the way to go as would break other modules. https://mdxjs.com/community/contribute/#site is informative, maybe a specific script to check the node/npm version would have helped as a developer.

Thx also for the infos about current and future support of node.