React组件编译失败求助：npm包引入后提示需适配对应loader

你遇到的核心问题是发布到npm的组件源码没有被转译为兼容的ES5/ES语法，导致使用该组件的项目无法解析JSX语法（报错里的<div就是JSX未被转译的直接证据）。本地开发时你的开发环境（比如Webpack+Babel）会自动处理JSX，但发布到npm的如果是未转译的源码，使用方的构建工具默认不会对node_modules里的文件做转译，所以才会出现这个解析错误。

下面是具体的解决步骤：

1. 用Babel转译你的组件代码 #

首先需要确保你的组件代码被转译为浏览器和其他项目能直接解析的代码：

• 安装Babel依赖：

npm install --save-dev @babel/core @babel/preset-env @babel/preset-react babel-cli

• 在项目根目录创建babel.config.js文件，配置React和环境预设：

module.exports = {
  presets: [
    ['@babel/preset-env', { targets: { node: 'current' } }],
    '@babel/preset-react'
  ]
};

• 在package.json里添加打包脚本，将源码转译到dist目录：

"scripts": {
  "build": "babel src --out-dir dist"
}

• 运行npm run build，生成转译后的代码到dist文件夹。

2. 配置package.json的入口与发布内容 #

确保npm发布的是转译后的代码，而不是源码：

• 修改main字段，指向转译后的入口文件：

"main": "dist/heatMapGraph.js"

• 添加files字段，指定npm需要发布的文件（只包含转译后的dist文件夹即可）：

"files": [
  "dist"
]

• 也可以用.npmignore文件排除不需要发布的内容（比如src、node_modules、配置文件等），和files字段二选一即可。

3. 重新发布你的npm包 #

• 更新版本号（npm要求每次发布版本号唯一）：

npm version patch # 小版本更新，也可以用minor/major

• 重新发布：

npm publish

额外优化方案：使用Rollup/Webpack打包组件 #

如果需要更好的兼容性（比如生成UMD、ES模块等多种格式），可以用Rollup或者Webpack来打包组件。比如Rollup配合@rollup/plugin-babel、@rollup/plugin-react插件，能生成更精简的分发代码，更适合React组件的发布场景。

临时应急方案（不推荐） #

如果暂时无法重新发布组件，也可以让使用该组件的项目修改Babel配置，将你的包加入转译白名单：
在使用方的babel.config.js或者webpack.config.js里，添加你的包名到需要转译的列表中，比如：

module.exports = {
  presets: [...],
  include: [
    path.resolve(__dirname, 'src'),
    path.resolve(__dirname, 'node_modules/heatmap-calendar-react')
  ]
};

不过这个方案会增加使用方的配置成本，优先推荐前面的组件转译后发布的方案。

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