From 9d89490dbb0a132a17153175e28c5480f07b82ac Mon Sep 17 00:00:00 2001
From: Stefan Zimmermann <user@zimmermann.co>
Date: Sun, 10 Apr 2022 00:44:53 +0200
Subject: [PATCH] docs: Describe current issue w/CRA 5 integration

---
 docs/docs/getting-started.server.mdx | 41 ++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx
index bda8b931e..b3f9ca736 100644
--- a/docs/docs/getting-started.server.mdx
+++ b/docs/docs/getting-started.server.mdx
@@ -508,6 +508,47 @@ through webpack loader syntax in imports.
 Install the webpack loader [`@mdx-js/loader`][mdx-loader].
 There is no need to configure it.
 
+However, to avoid the [ESLint](http://eslint.org)-unfriendly
+`!@mdx-js/loader!` import prefix, the loader can be added to webpack’s config,
+using a [`react-scripts`](http://github.com/facebook/create-react-app/tree/main/packages/react-scripts)
+rewiring tool, like [CRACO](http://github.com/gsoft-inc/craco).
+
+<details>
+  <summary>Expand CRACO example</summary>
+
+  ```js path="craco.config.js"
+  const { addAfterLoader, loaderByName } = require('@craco/craco')
+
+  module.exports = {
+    webpack: {
+      configure: (webpackConfig) => {
+        addAfterLoader(webpackConfig, loaderByName('babel-loader'), {
+          test: /\.(md|mdx)$/,
+          loader: require.resolve('@mdx-js/loader')
+        })
+
+        return webpackConfig
+      }
+    }
+  }
+  ```
+
+  ```jsx path="src/App.jsx"
+  import Content from './content.mdx'
+
+  export default function App() {
+    return <Content />
+  }
+  ```
+</details>
+
+<Note type="info">
+  **Note**: due to [broken MDX import forwarding](http://github.com/facebook/create-react-app/issues/12166)
+  in `react-scripts` 5.x, rewiring is currently the most viable option when
+  using CRA 5. There’s an [ongoing discussion](http://github.com/mdx-js/mdx/discussions/1870)
+  about this issue.
+</Note>
+
 See also [¶ Webpack][webpack], which is used in CRA, and see [¶ React][react],
 which you’re likely using, for more info.