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 :)