diff --git a/README.md b/README.md index 0f53ec2..c699666 100644 --- a/README.md +++ b/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. - -
+If you have some errors when using Next.js, check [here](https://pro-chat.antdigital.dev/en-US/guide/nextjs#frequently-asked-questions]). ## 🔨 Usage diff --git a/README.zh-CN.md b/README.zh-CN.md index 5eda5c2..dd753bc 100644 --- a/README.zh-CN.md +++ b/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 中运行了 - -
+如果在 Next.js 项目中遇到一些报错,请参考这里[解决](https://pro-chat.antdigital.dev/guide/nextjs#常见问题]). ## 🔨 使用 diff --git a/docs/guide/nextjs.en-US.md b/docs/guide/nextjs.en-US.md index c3bfed5..7de3367 100644 --- a/docs/guide/nextjs.en-US.md +++ b/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. diff --git a/docs/guide/nextjs.md b/docs/guide/nextjs.md index 96b7a09..c113156 100644 --- a/docs/guide/nextjs.md +++ b/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),因此也需要将涉及的依赖配置到插件中。