Add CRA 5 production build guidance

docs/web/getting-started-react.md

@@ -28,6 +28,10 @@ npm install
 
 If you are adding Reveal SDK to an existing React application, you can skip this step.
 
+:::caution Existing Create React App applications
+Existing Create React App 5 applications using `react-scripts@5.0.1` may experience production-build issues. Create React App has been deprecated by the React team; Vite, as shown in this guide, is recommended for new applications and migrations where practical. See [Create React App 5 Production Builds](known-issues.md#create-react-app-5-production-builds) for guidance.
+:::
+
 ## Step 2 - Install the Reveal SDK Client
 
 Install the `reveal-sdk` package.

docs/web/known-issues.md

@@ -31,6 +31,42 @@ There are two options to resolve this:
    If you must remain on Windows, host the application inside a **Windows Container**.
    This allows installing and configuring Playwright within the container image, bypassing the Windows App Service limitation.
 
+## Create React App 5 Production Builds
+
+### Issue
+
+Existing Create React App 5 applications using `react-scripts@5.0.1` may experience very long production build times or appear to stall when consuming Reveal SDK from npm.
+
+### Cause and Context
+
+This occurs when the Create React App/Webpack production pipeline processes the Reveal ESM bundle. Create React App has been deprecated by the React team. For new applications, or migrations where practical, use a maintained React framework or a modern build tool such as Vite.
+
+### Workaround
+
+For an existing Create React App application that cannot migrate yet:
+
+1. Copy `node_modules/reveal-sdk/dist/reveal-sdk.js` and `node_modules/reveal-sdk/dist/locales/` to `public/reveal/`.
+2. Add the IIFE bundle to `public/index.html`:
+
+```html
+<script src="%PUBLIC_URL%/reveal/reveal-sdk.js"></script>
+```
+
+3. Configure Webpack externals in your CRA override:
+
+```js
+config.externals = {
+    ...(config.externals || {}),
+    "reveal-sdk": "Reveal",
+};
+```
+
+4. Continue to import Reveal from npm in your application:
+
+```ts
+import * as Reveal from "reveal-sdk";
+```
+
 ## Custom Visualizations Not Supported on Export
 
 ### Issue

docs/web/upgrade-guide-v2.0.0.md

@@ -73,6 +73,10 @@ import { RevealSdkSettings, RevealView } from "reveal-sdk";
   </TabItem>
 </Tabs>
 
+:::caution Create React App 5 applications
+If your application uses Create React App 5 with `react-scripts@5.0.1`, see [Create React App 5 Production Builds](known-issues.md#create-react-app-5-production-builds) for production-build guidance before switching the Reveal client to npm.
+:::
+
 :::tip Still need script tags?
 The SDK distribution zip is still available for non-bundler setups — jQuery and Day.js are no longer needed: