Docusaurus是否支持使用NPM包提供的React组件？

核心结论 #

Docusaurus完全支持安装使用第三方React NPM包，你遇到的Chakra UI Switch组件未正常渲染问题，是Chakra UI本身的全局样式Provider依赖未配置导致的，和Docusaurus的MDX组件能力无关。

解决步骤 #

• 第一步：安装Chakra UI完整依赖
  Chakra UI运行需要三个peer依赖，你需要先完整安装所有包：

npm i @chakra-ui/react @emotion/react @emotion/styled framer-motion
# 或使用yarn
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion

• 第二步：全局注入ChakraProvider
  Chakra UI的所有组件都需要包裹在ChakraProvider下才能正常加载样式和交互逻辑，你可以通过Docusaurus的自定义Root组件全局注入：

1. 在你的Docusaurus项目下创建src/theme/Root.js文件
2. 写入以下代码：

import React from 'react';
import { ChakraProvider } from '@chakra-ui/react';

export default function Root({ children }) {
  return <ChakraProvider>{children}</ChakraProvider>;
}

• 第三步：验证组件使用
  完成上述配置后重启项目，你之前在MDX文件中写的Switch组件代码即可正常渲染。如果出现hydration mismatch报错，可以用Docusaurus自带的ClientOnly组件包裹Chakra组件，避免SSR阶段的渲染差异：

import ClientOnly from '@docusaurus/ClientOnly';
import { Switch } from "@chakra-ui/react";

<ClientOnly>
  {() => <Switch>test</Switch>}
</ClientOnly>

通用注意事项 #

• 不带全局Provider依赖、不需要操作浏览器API的纯React组件，可以直接在MDX文件中导入使用，无需额外配置
• 依赖浏览器API、仅能在客户端运行的组件，都需要用ClientOnly组件包裹，避免构建或SSR阶段报错

内容的提问来源于stack exchange，提问作者Felpato