求助：如何将React组件发布至NPM？已尝试多方案未果

一、项目初始化与依赖配置 #

• 创建项目文件夹并初始化：mkdir react-ui-component && cd react-ui-component && npm init -y
• 安装React相关依赖为peer依赖（避免打包进组件库）：npm install react react-dom --save-peer
• 若使用TypeScript，安装开发依赖：npm install typescript @types/react @types/react-dom --save-dev
• 配置tsconfig.json（核心字段示例）：

  {
    "compilerOptions": {
      "target": "ES6",
      "module": "ESNext",
      "declaration": true,
      "outDir": "./dist",
      "jsx": "react-jsx",
      "strict": true,
      "moduleResolution": "node"
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
  }
  

二、配置Rollup打包（推荐用于库构建） #

• 安装Rollup及必要插件：npm install rollup @rollup/plugin-node-resolve @rollup/plugin-commonjs @rollup/plugin-typescript --save-dev
• 创建rollup.config.js配置文件：

  import resolve from '@rollup/plugin-node-resolve';
  import commonjs from '@rollup/plugin-commonjs';
  import typescript from '@rollup/plugin-typescript';
  
  export default {
    input: 'src/index.tsx',
    output: [
      {
        file: 'dist/index.cjs.js',
        format: 'cjs',
        sourcemap: true
      },
      {
        file: 'dist/index.es.js',
        format: 'es',
        sourcemap: true
      }
    ],
    external: ['react', 'react-dom'],
    plugins: [
      resolve(),
      commonjs(),
      typescript({ tsconfig: './tsconfig.json' })
    ]
  };
  

三、编写组件与入口文件 #

• 在src目录下编写你的React组件（例如Button.tsx）
• 创建src/index.tsx作为入口，导出组件：

  export { default as Button } from './Button';
  

四、完善package.json关键配置 #

• 修改核心字段：

  {
    "main": "dist/index.cjs.js",
    "module": "dist/index.es.js",
    "types": "dist/index.d.ts",
    "files": ["dist", "README.md"],
    "scripts": {
      "build": "rollup -c"
    },
    "private": false
  }
  

• 补充peerDependencies版本范围（示例）：

  "peerDependencies": {
    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
  }
  

五、本地测试组件 #

• 执行npm run build生成构建产物
• 运行npm link将本地包链接到全局
• 新建一个测试React项目，运行npm link your-package-name（替换为你的包名），导入组件验证功能正常

六、发布到NPM #

• 登录NPM账号：npm login（按提示输入用户名、密码、邮箱）
• 再次执行npm run build确保产物最新
• 发布包：npm publish（若为私有包，添加--access private参数）

常见问题排查 #

• 若发布后组件无法导入：检查package.json的main/module/types路径是否正确，确认dist文件已包含在发布文件中
• 若出现React重复实例错误：确认Rollup配置中external已包含react和react-dom，且peerDependencies配置正确
• 类型提示缺失：检查tsconfig.json中declaration是否设为true，dist目录是否生成了.d.ts文件

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