diff --git a/docs/web/getting-started-react.md b/docs/web/getting-started-react.md
index 6f51bfc7..f420b6d0 100644
--- a/docs/web/getting-started-react.md
+++ b/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.
diff --git a/docs/web/known-issues.md b/docs/web/known-issues.md
index 5518b9f5..7059cba5 100644
--- a/docs/web/known-issues.md
+++ b/docs/web/known-issues.md
@@ -31,6 +31,62 @@ 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, configure Webpack to resolve `reveal-sdk` to the browser (IIFE) bundle at runtime. **Both the Webpack external and the IIFE bundle are required**: the external alone leaves the import without a runtime implementation, and the IIFE alone still leaves the ESM package in Webpack's production pipeline.
+
+Create React App does not expose its Webpack configuration, so this requires an override tool. The following steps use [react-app-rewired](https://github.com/timarney/react-app-rewired). If your application already uses [CRACO](https://craco.js.org/), apply the same `externals` change in `craco.config.js` instead.
+
+1. Install `react-app-rewired` and use it to build the application.
+
+   ```bash npm2yarn
+   npm install react-app-rewired --save-dev
+   ```
+
+   ```json title="package.json"
+   "scripts": {
+       "start": "react-app-rewired start",
+       "build": "react-app-rewired build"
+   }
+   ```
+
+2. Create `config-overrides.js` in the project root and configure the Webpack external.
+
+   ```js title="config-overrides.js"
+   module.exports = function override(config) {
+       config.externals = {
+           ...(config.externals || {}),
+           "reveal-sdk": "Reveal",
+       };
+
+       return config;
+   };
+   ```
+
+3. Copy `node_modules/reveal-sdk/dist/reveal-sdk.js` and `node_modules/reveal-sdk/dist/locales/` to `public/reveal/`, keeping the published layout. The SDK resolves its locale files relative to `reveal-sdk.js`, so no additional locale configuration is required.
+
+4. Add the IIFE bundle to `public/index.html`:
+
+   ```html
+   <script src="%PUBLIC_URL%/reveal/reveal-sdk.js"></script>
+   ```
+
+5. Continue to import Reveal from npm in your application:
+
+   ```ts
+   import * as Reveal from "reveal-sdk";
+   ```
+
 ## Custom Visualizations Not Supported on Export
 
 ### Issue
diff --git a/docs/web/upgrade-guide-v2.0.0.md b/docs/web/upgrade-guide-v2.0.0.md
index 0ae5e54b..7fddb660 100644
--- a/docs/web/upgrade-guide-v2.0.0.md
+++ b/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:
 
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/getting-started-react.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/getting-started-react.md
index e8825149..7eabf954 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current/web/getting-started-react.md
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/web/getting-started-react.md
@@ -28,6 +28,10 @@ npm install
 
 既存の React アプリケーションに Reveal SDK を追加する場合は、この手順をスキップできます。
 
+:::caution 既存の Create React App アプリケーション
+`react-scripts@5.0.1` を使用している既存の Create React App 5 アプリケーションでは、本番ビルドに問題が発生する場合があります。Create React App は React チームによって非推奨とされています。新しいアプリケーション、および移行が現実的な場合は、このガイドで示すように Vite を推奨します。ガイダンスについては、[Create React App 5 の本番ビルド](known-issues.md#create-react-app-5-production-builds) を参照してください。
+:::
+
 ## 手順 2 - Reveal SDK クライアントをインストールする
 
 `reveal-sdk` パッケージをインストールします。
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/known-issues.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/known-issues.md
index 35d84f98..575b86f8 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current/web/known-issues.md
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/web/known-issues.md
@@ -31,6 +31,62 @@
    Windows 環境を維持する必要がある場合は、アプリケーションを **Windows コンテナー**内でホストします。
    これにより、コンテナー イメージ内で Playwright をインストールおよび構成でき、Windows App Service の制限を回避できます。
 
+## Create React App 5 の本番ビルド {#create-react-app-5-production-builds}
+
+### 問題
+
+`react-scripts@5.0.1` を使用している既存の Create React App 5 アプリケーションでは、Reveal SDK を npm から使用する際に、本番ビルドに非常に長い時間がかかる、またはビルドが停止したように見える場合があります。
+
+### 原因と背景
+
+これは、Create React App/Webpack の本番ビルド パイプラインが Reveal の ESM バンドルを処理する際に発生します。Create React App は React チームによって非推奨とされています。新しいアプリケーションの場合、または移行が現実的な場合は、メンテナンスされている React フレームワークや、Vite などの最新のビルド ツールを使用してください。
+
+### 回避策
+
+まだ移行できない既存の Create React App アプリケーションでは、実行時に `reveal-sdk` がブラウザー (IIFE) バンドルに解決されるように Webpack を構成します。**Webpack の external と IIFE バンドルの両方が必要です**。external のみの場合、実行時にインポートの実装が存在しません。また、IIFE のみの場合、ESM パッケージが Webpack の本番パイプラインに残ります。
+
+Create React App は Webpack 構成を公開していないため、オーバーライド ツールが必要です。以下の手順では [react-app-rewired](https://github.com/timarney/react-app-rewired) を使用します。アプリケーションですでに [CRACO](https://craco.js.org/) を使用している場合は、同じ `externals` の変更を `craco.config.js` に適用してください。
+
+1. `react-app-rewired` をインストールし、アプリケーションのビルドに使用します。
+
+   ```bash npm2yarn
+   npm install react-app-rewired --save-dev
+   ```
+
+   ```json title="package.json"
+   "scripts": {
+       "start": "react-app-rewired start",
+       "build": "react-app-rewired build"
+   }
+   ```
+
+2. プロジェクトのルートに `config-overrides.js` を作成し、Webpack の external を構成します。
+
+   ```js title="config-overrides.js"
+   module.exports = function override(config) {
+       config.externals = {
+           ...(config.externals || {}),
+           "reveal-sdk": "Reveal",
+       };
+
+       return config;
+   };
+   ```
+
+3. `node_modules/reveal-sdk/dist/reveal-sdk.js` と `node_modules/reveal-sdk/dist/locales/` を、公開されているレイアウトを維持したまま `public/reveal/` にコピーします。SDK はロケール ファイルを `reveal-sdk.js` からの相対パスで解決するため、追加のロケール構成は必要ありません。
+
+4. IIFE バンドルを `public/index.html` に追加します。
+
+   ```html
+   <script src="%PUBLIC_URL%/reveal/reveal-sdk.js"></script>
+   ```
+
+5. アプリケーションでは、引き続き npm から Reveal をインポートします。
+
+   ```ts
+   import * as Reveal from "reveal-sdk";
+   ```
+
 ## エクスポート時にカスタム表示形式がサポートされない
 
 ### 問題
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/upgrade-guide-v2.0.0.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/upgrade-guide-v2.0.0.md
index 4ff715c1..645813a6 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current/web/upgrade-guide-v2.0.0.md
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/web/upgrade-guide-v2.0.0.md
@@ -73,6 +73,10 @@ import { RevealSdkSettings, RevealView } from "reveal-sdk";
   </TabItem>
 </Tabs>
 
+:::caution Create React App 5 アプリケーション
+アプリケーションで Create React App 5 と `react-scripts@5.0.1` を使用している場合は、Reveal クライアントを npm に切り替える前に、[Create React App 5 の本番ビルド](known-issues.md#create-react-app-5-production-builds) で本番ビルドに関するガイダンスを参照してください。
+:::
+
 :::tip スクリプトタグが必要ですか?
 バンドラーを使用しない環境向けに SDK 配布 zip は引き続き利用可能ですが、jQuery と Day.js は不要になりました: