本文深入探讨了在开发基于Mantine的React组件库并发布为npm包时，遇到的TypeError: Cannot read properties of null (reading ‘useContext’)错误。该问题通常源于组件库在构建时未正确配置为ESM模块输出，导致在消费应用中无法正确访问Mantine的上下文。教程将详细指导如何通过调整tsconfig.json将TypeScript项目编译为ESM模块，从而彻底解决此问题，确保Mantine组件在外部项目中正常运行。

Mantine组件库开发中的useContext错误解析

在构建基于mantine ui的react组件库并将其发布为npm包时，开发者可能会遇到一个常见的运行时错误：typeerror: cannot read properties of null (reading ‘usecontext’)。尽管mantine组件通常需要在mantineprovider的包裹下才能正常工作，但即使在消费应用中正确配置了mantineprovider，这个错误仍然可能出现，令人困惑。

这个错误的核心在于Mantine组件内部对React Context的依赖。Mantine等许多现代UI库都广泛使用React Context来管理主题、样式、方向等全局配置。当一个Mantine组件被打包成一个独立的npm包，并在另一个项目中被引用时，如果打包过程没有正确处理模块的解析和导出，就可能导致这个Context无法被正确访问，从而抛出useContext相关的错误。

问题根源：模块编译与ESM缺失

经过深入分析，此类问题往往并非MantineProvider本身缺失，而是组件库的构建输出格式与消费应用的期望不符。具体来说，当使用TypeScript开发组件库时，如果tsconfig.json配置将代码编译为CommonJS (CJS) 模块，而消费应用（或Mantine内部）期望的是ECMAScript Modules (ESM)，就会发生不匹配。这种不匹配会导致React在尝试解析组件内部的Context时失败，因为模块加载器无法正确地建立起Mantine组件与MantineProvider之间的Context连接。

解决方案：配置TypeScript为ESM输出

解决此问题的关键在于确保组件库在编译时输出为ESM模块。这可以通过修改项目的tsconfig.json文件来实现。以下是一个经过优化的tsconfig.json配置示例，它将TypeScript代码编译为ESM格式，并生成类型声明文件，这对于发布npm包至关重要。

{   "exclude": ["node_modules"],   "include": ["src"],   "compilerOptions": {     "module": "ES2020", // 核心配置：指定模块系统为ESM     "declaration": true, // 生成类型声明文件 (.d.ts)     "outDir": "dist/esm", // ESM输出目录     "esModuleInterop": true, // 启用ES模块和CommonJS模块之间的互操作性     "forceConsistentCasingInFileNames": true, // 强制文件名大小写一致     "removeComments": true, // 移除编译后的注释     "strict": true, // 启用所有严格类型检查选项     "skipLibCheck": true, // 跳过所有声明文件（.d.ts）的类型检查     "jsx": "react", // JSX编译模式     "moduleResolution": "node", // 模块解析策略     "lib": ["dom", "es2016", "esnext.asynciterable"], // 包含的库文件     "sourceMap": true, // 生成源映射文件     "declarationDir": "dist/types" // 类型声明文件输出目录   } }

关键配置项解释：

• “module”: “ES2020”: 这是最核心的改动，它指示TypeScript编译器将代码编译为ECMAScript 2020模块。这确保了组件库的输出是标准的ESM格式，能够被现代打包工具和运行时正确解析。
• “declaration”: true 和 “declarationDir”: “dist/types”: 这些配置用于生成TypeScript类型声明文件（.d.ts），这对于使用TypeScript的消费项目来说至关重要，提供了类型提示和检查。
• “outDir”: “dist/esm”: 指定了编译后的JavaScript文件（ESM格式）的输出目录。建议将ESM输出与CJS输出（如果也需要）分开，以提供更好的模块兼容性。
• “esModuleInterop”: true: 允许在CommonJS模块中以ESM的方式导入，这在处理第三方库时非常有用，可以避免一些导入错误。
• “jsx”: “react”: 指定JSX的编译方式，对于React组件库是必需的。

示例组件代码（无需修改）

原始的Mantine组件代码通常不需要为解决此问题而进行修改。例如，一个简单的Mantine按钮组件可能如下所示：

import React from "react"; import { Button as MantineButton } from "@mantine/core"; import PropTypes from "prop-types";  const ButtonTest = ({ label, backgroundColor = "red", handleClick }) => {   const style = {     backgroundColor,     border: "none",     padding: "10px",   };   return (     <div>       <MantineButton onClick={handleClick} style={style}>         {label}       </MantineButton>     </div>   ); };  ButtonTest.propTypes = { // 注意：这里应为propTypes，而非prototypes   label: PropTypes.string,   backgroundColor: PropTypes.string,   handleClick: PropTypes.func, };  export default ButtonTest;

（注意：原始代码中的ButtonTest.prototypes应为ButtonTest.propTypes，这是React的PropType定义标准。）

腾讯元宝

腾讯混元平台推出的ai助手

246

查看详情

这个组件本身是符合Mantine和React规范的。问题不在于组件的实现，而在于它被打包后的模块格式。

发布与消费组件库

在修改tsconfig.json并重新编译组件库后，确保你的package.json也正确配置了main、module和types字段，以指向正确的入口文件：

{   "name": "your-component-library",   "version": "1.0.0",   "main": "dist/cjs/index.js", // 如果需要CommonJS版本   "module": "dist/esm/index.js", // ESM版本入口   "types": "dist/types/index.d.ts", // 类型声明文件入口   "files": ["dist"],   "exports": { // 推荐使用exports字段提供更细粒度的模块解析     ".": {       "import": "./dist/esm/index.js",       "require": "./dist/cjs/index.js",       "types": "./dist/types/index.d.ts"     }   },   // ... 其他字段 }

在消费应用中，当您通过npm安装并使用此组件库时，现代打包工具（如Webpack, Rollup, Vite）将能够根据package.json中的module或exports.import字段，优先加载ESM版本的组件，从而正确地解析Mantine的Context，避免useContext错误。

注意事项与总结

1. MantineProvider的必要性：即使解决了模块编译问题，Mantine组件仍然需要在消费应用的根组件或父组件中被MantineProvider包裹。本教程解决的是在MantineProvider已存在的情况下仍然报错的问题。
2. 兼容性考虑：如果您的组件库需要同时支持CommonJS和ESM环境，您可能需要配置两个不同的tsconfig.json（或一个配置配合不同的构建脚本），分别输出到dist/cjs和dist/esm，并在package.json中通过main和module字段或exports字段进行指向。
3. 构建工具：本教程主要关注tsc的配置。如果您使用Rollup、Webpack等打包工具，也需要确保它们的配置能够正确处理TypeScript编译并输出为ESM。
4. package.json的type字段：在一些情况下，您可能还需要在package.json中添加”type”: “module”来明确指示整个包的默认模块系统是ESM。

通过将TypeScript组件库正确编译为ESM模块，我们能够有效地解决Mantine组件在发布为npm包后出现的TypeError: Cannot read properties of null (reading ‘useContext’)问题。这不仅确保了组件的正常运行，也符合现代JavaScript模块化的最佳实践。