📝 docs: add solutions for nextjs problems (#308)

README.md

@@ -56,25 +56,7 @@ $ pnpm install antd // peerDependencies
 
 ### Compile with Next.js
 
-> \[!NOTE]
->
-> By work correct with Next.js SSR, add `transpilePackages: ['@ant-design/pro-chat']` to `next.config.js`. For example:
-
-```js
-const nextConfig = {
-  transpilePackages: [
-    '@ant-design/pro-chat',
-    '@ant-design/pro-editor',
-    'react-intersection-observer',
-  ],
-};
-```
-
-> \[!NOTE]
->
-> If you are using a new version of NextJs (higher than 14), you no longer need to configure transpilePackages to run in NextJs.
-
-<br/>
+If you have some errors when using Next.js, check [here](https://pro-chat.antdigital.dev/en-US/guide/nextjs#frequently-asked-questions]).
 
 ## 🔨 Usage
 

README.zh-CN.md

@@ -55,23 +55,7 @@ $ pnpm install antd  // peerDependencies
 
 ### 使用 Next.js 进行编译
 
-> \[!NOTE]\
-> 为了正确使用 Next.js SSR，请在 `next.config.js` 中添加 `transpilePackages: ['@ant-design/pro-chat']`。例如：
-
-```js
-const nextConfig = {
-  transpilePackages: [
-    '@ant-design/pro-chat',
-    '@ant-design/pro-editor',
-    'react-intersection-observer',
-  ],
-};
-```
-
-> \[!NOTE]\
-> 如果你使用的是新版本的 NextJs(higher than 14)，现在不需要你配置 transpilePackages 也可以在 NextJs 中运行了
-
-<br/>
+如果在 Next.js 项目中遇到一些报错，请参考这里[解决](https://pro-chat.antdigital.dev/guide/nextjs#常见问题]).
 
 ## 🔨 使用
 

docs/guide/nextjs.en-US.md

@@ -8,43 +8,27 @@ nav:
   order: 0
 ---
 
-## Integrate with Next.js
+## Integration with Next.js
 
-[Next.js](https://nextjs.org/) is a very popular research and development framework in the community. The integration of ProChat and Next.js is also very easy.
+[Next.js](https://nextjs.org/) is a very popular development framework in the community. Integrating ProChat with Next.js is also very easy.
 
-```bash
-npx create-next-app@latest
-```
-
-### Dependent installation
+### Create Project with Official Scaffold
 
 ```bash
-npm install @ant-design/pro-chat --save
-or
-pnpm install @ant-design/pro-chat
+pnpm dlx create-next-app@latest
 ```
 
-Due to Next.js being a CSR, SSR isomorphic React framework, and ProChat only providing the ESM module by default, after installation, it is necessary to go to ` next.config. ' (m) Add relevant dependencies to 'transpilePackages' in JavaScript:
+### Install Dependencies
 
-> In the latest version of NextJS 14 AppRoute, configuration is no longer required
-
-```js
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  // Convert pure ESM modules to node compatible modules
-  transpilePackages: [
-    '@ant-design/pro-chat',
-    'react-intersection-observer',
-    '@ant-design/pro-editor',
-  ],
-};
+```bash
+pnpm add @ant-design/pro-chat antd-style antd
 ```
 
 ### Usage
 
-Next, use it the same as other components.
+Next, use it just like any other component.
 
-If you are in a project created by default scaffolding, simply write the following code in 'page. js | tsx' to see ProChat.
+If you are using a project created with the default scaffold, you can see ProChat by writing the following code directly in `page.tsx`.
 
 ```js
 "use client";
@@ -83,3 +67,47 @@ export default function Home() {
 ```
 
 > A more complete demo can view the Case in the model case [Model Case - ChatGPT](./chatgpt.md)
+
+### Frequently Asked Questions
+
+If you encounter issues with module imports or syntax errors during use, the primary reasons are:
+
+- Next.js is an isomorphic React framework for both CSR and SSR. The code execution environment includes both the browser and Node.js.
+
+- Both @ant-design/pro-chat and its underlying dependency @ant-design/pro-editor use the [Bundless](https://github.com/umijs/father/blob/master/docs/guide/build-mode.md) build mode of father, and only provide ESModule outputs.
+
+- Therefore, there may be ESModule syntax incompatibility issues, and additional transpile and bundle processing for related dependencies may be required.
+
+### Solutions
+
+It is recommended to use pnpm instead of npm as the package manager, as some issues can be resolved with the resolution of ghost dependencies.
+
+- Next.js version >= v13.0.0 (Recommended)
+
+Add the dependencies that cause errors to the [transpilePackages](https://nextjs.org/docs/app/api-reference/next-config-js/transpilePackages) configuration item, such as:
+
+```js
+const nextConfig = {
+  transpilePackages: [
+    // Add as needed based on actual situation
+    'shiki',
+    '@ant-design/pro-chat',
+    '@ant-design/pro-editor',
+  ],
+};
+```
+
+- Next.js version < v13.0 (Not Recommended)
+
+Install the [next-transpile-modules](https://github.com/martpie/next-transpile-modules) plugin and configure the dependencies that need to be transpiled, such as:
+
+```js
+const withTM = require('next-transpile-modules')([
+  // Refer to the plugin documentation for specific usage
+  '.pnpm/node_modules/@ant-design/pro-editor',
+  '@ant-design/pro-chat',
+]);
+module.exports = withTM({});
+```
+
+Due to an [issue](https://github.com/vercel/next.js/issues/19936) in older versions of Next.js where global CSS cannot be imported from node_modules, the involved dependencies also need to be configured in the plugin.

docs/guide/nextjs.md

@@ -12,39 +12,23 @@ nav:
 
 [Next.js](https://nextjs.org/) 是社区中非常流行的研发框架。ProChat 与 Next.js 的集成也非常容易。
 
+### 官方脚手架创建项目
+
 ```bash
-npx create-next-app@latest
+pnpm dlx create-next-app@latest
 ```
 
 ### 依赖安装
 
 ```bash
-npm install @ant-design/pro-chat --save
-or
-pnpm install @ant-design/pro-chat
-```
-
-由于 Next.js 是一个 CSR、SSR 同构的 React 框架，而 ProChat 默认只提供 esm 模块，因此在安装后，需要在 `next.config.(m)js` 中 `transpilePackages` 中加入相关依赖：
-
-> 在最新版本 NextJS 14 AppRoute 中可以不需要配置了
-
-```js
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  // 将纯 esm 模块转为 node 兼容模块
-  transpilePackages: [
-    '@ant-design/pro-chat',
-    'react-intersection-observer',
-    '@ant-design/pro-editor',
-  ],
-};
+pnpm add @ant-design/pro-chat antd-style antd
 ```
 
 ### 使用
 
 接下来和其他组件一样使用即可。
 
-如果你是默认脚手架创建出来的项目中，直接在 `page.js|tsx` 中写下如下代码就可以看到 ProChat 了。
+如果你是默认脚手架创建出来的项目中，直接在 `page.tsx` 中写下如下代码就可以看到 ProChat 了。
 
 ```js
 "use client";
@@ -83,3 +67,47 @@ export default function Home() {
 ```
 
 > 更加完整的 Demo 可以查看模型案例中的 Case [模型案例 - ChatGPT](./chatgpt.md)
+
+### 常见问题
+
+如果使用过程中，出现模块的导入问题或语法报错，核心原因是：
+
+- Next.js 是一个 CSR、SSR 同构的 React 框架。代码执行环境不仅有浏览器也有 Node.js。
+
+- 不论是 @ant-design/pro-chat 还是其底层依赖 @ant-design/pro-editor，都采用了 father 的 [Bundless](https://github.com/umijs/father/blob/master/docs/guide/build-mode.md) 构建模式，且仅提供 ESModule 产物。
+
+- 因此可能出现 ESModule 语法不兼容问题，此时需要对相关依赖进行额外的 transpile 和 bundle 处理。
+
+### 解决方案
+
+包管理工具推荐使用 pnpm 而不是 npm，部分问题可以随着幽灵依赖的解决而解决。
+
+#### Next.js 版本 >= v13.0.0（推荐）
+
+将报错的依赖添加到 [transpilePackages 配置项](https://nextjs.org/docs/app/api-reference/next-config-js/transpilePackages)中，如：
+
+```js
+const nextConfig = {
+  transpilePackages: [
+    // 根据实际情况按需添加
+    'shiki',
+    '@ant-design/pro-chat',
+    '@ant-design/pro-editor',
+  ],
+};
+```
+
+#### Next.js 版本 < v13.0（不推荐）
+
+安装 [next-transpile-modules 插件](https://github.com/martpie/next-transpile-modules)，配置需要 transpile 的依赖，如：
+
+```js
+const withTM = require('next-transpile-modules')([
+  // 具体使用参考插件文档
+  '.pnpm/node_modules/@ant-design/pro-editor',
+  '@ant-design/pro-chat',
+]);
+module.exports = withTM({});
+```
+
+由于旧版本的 Next.js 存在无法从 node_modules 中导入全局 CSS 的[问题](https://github.com/vercel/next.js/issues/19936)，因此也需要将涉及的依赖配置到插件中。