使用npm发布一个react组件（踩坑实践）

前端小黑
18,396 阅读10分钟

前言

  • 本文主要记录本人在使用 NPM 发布具有样式的 react组件 时的完整实践流程，在这过程中踩了许多坑，花在完善发布脚手架的时间远多于开发组件的时间，于是记录下整个过程，希望能给大家提供帮助。

  • 下文的内容主要包括：

    • 发布 react组件 的脚手架搭建。
    • 开发组件。
    • 打包组件，并在测试项目中引入打包组件模块，验证组件功能。
    • 发布到 NPM。

脚手架搭建

创建项目

  • 首先创建项目文件夹，并使用 npm init 命令生成初始的配置文件 package.json，具体命令如下：
mkdir react-component-npm-cli
cd react-component-npm-cli
npm init
  • 在使用 npm init 命令 的时候，会提示我们输入项目的名称、版本号、作者等，可以一路回车，稍后进行修改。或者直接使用下面的命令采用默认配置，后面再根据自己的需要进行修改：
npm init -y
  • 这一步完成后，我们的项目文件夹里就会新增一个 package.json 文件。接下来完善脚手架，创建如下的目录结构：
├── config  # webpack配置
     ├── webpack.base.js # 公共配置
     ├── webpack.dev.config.js # 开发环境配置
     └── webpack.prod.config.js # 打包发布环境配置
├── example # 开发时预览代码
       ├── src # 示例代码目录
            ├── app.js # 入口 js 文件
            └── index.html # 入口 html 文件
├── lib # 组件打包结果目录
├── node_modules # 安装依赖时自动生成
├── src # 组件源代码目录
     ├── index.css # 组件样式
     └── index.js  # 组件源代码
├── .babelrc # babel 配置
├── .npmignore # 指定发布 npm 的时候需要忽略的文件和文件夹
├── README.md
└── package.json

安装依赖

  • 首先安装 react 相关的依赖：
npm i react react-dom -D
  • 接着安装 babel 编译相关的依赖：
npm i @babel/cli @babel/core @babel/preset-env @babel/preset-react -D
  • 本项目采用 webpack 做构建，同时使用 webpack-dev-server 作为本地开发服务器，使用 webpack-merge 合并webpack配置，因此使用下面的命令安装相关依赖：
npm i webpack webpack-cli webpack-dev-server webpack-merge -D
  • 同时，使用 babel-loader 编译 jsx，使用 MiniCssExtractPlugin 提取 css，安装命令如下：
npm i babel-loader mini-css-extract-plugin -D
  • 最后安装 style-loader 和 css-loader ，二者组合在一起使我们能够把样式表嵌入 webpack 打包后的 js 文件中（开发环境使用）。
  • 执行完以上命令，此时 package.json 中包含的依赖信息如下：
{
    "devDependencies": {
    // babel 用于将 es6+ 的代码转换成 es5
    "@babel/cli": "^7.5.5",
    "@babel/core": "^7.5.5",
    "@babel/preset-env": "^7.5.5", // 根据目标环境实现按需转码
    "@babel/preset-react": "^7.0.0", // 让babel支持react语法
    "babel-loader": "^8.0.6", // 编译 jsx
    "css-loader": "^3.2.0", // 将 css 装换成js
    "mini-css-extract-plugin": "^0.8.0", // 提取css
    "react": "^16.9.0",
    "react-dom": "^16.9.0",
    "style-loader": "^1.0.0", // 将 css 装换成js
    "webpack": "^4.39.3",
    "webpack-cli": "^3.3.7", // webpack4之后需要额外安装webpack-cli
    "webpack-dev-server": "^3.8.0", // 开发时预览组件所用的服务，在文件变化时会自动刷新页面
    "webpack-merge": "^4.2.2" // 用于合并webpack配置
  },
  "dependencies": {}
}

配置 webpack 和 babel

  • 如前面给出的目录结构所示，在 config 目录下我们建立 3 个 webpack 配置文件：
    • 公共配置文件：webpack.base.js。
    • 开发环境配置文件：webpack.dev.config.js。
    • 打包发布环境配置文件：webpack.prod.config.js。
  • 由于开发和发布打包时 webpack 配置有一部分是公共而且重复的，所以把这部分的配置单独拿出来放到webpack.base.js中，该文件内容如下：
module.exports = {
  module: {
    rules: [
      {
        // 使用 babel-loader 来编译处理 js 和 jsx 文件
        test: /\.(js|jsx)$/,
        use: "babel-loader",
        exclude: /node_modules/
      }
    ]
  },
};
  • 开发时采用的 webpack 配置写在 webpack.dev.config.js 中，内容如下：
const path = require('path');
const merge = require('webpack-merge');
const baseConfig = require('./webpack.base.js'); // 引用公共配置

const devConfig = {
  mode: 'development', // 开发模式
  entry: path.join(__dirname, "../example/src/app.js"), // 项目入口，处理资源文件的依赖关系
  output: {
    path: path.join(__dirname, "../example/src/"),
    filename: "bundle.js", // 使用webpack-dev-sevrer启动开发服务时，并不会实际在`src`目录下生成bundle.js，打包好的文件是在内存中的，但并不影响我们使用。
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        exclude: /\.min\.css$/,
        loader: ['style-loader','css-loader?modules'],
      },
      {
        test: /\.min\.css$/,
        loader: ['style-loader','css-loader'],
      },
    ]
  },
  devServer: {
    contentBase: path.join(__dirname, '../example/src/'),
    compress: true,
    host: '127.0.0.1', // webpack-dev-server启动时要指定ip，不能直接通过localhost启动，不指定会报错
    port: 3001, // 启动端口为 3001 的服务
    open: true // 自动打开浏览器
  },
};
module.exports = merge(devConfig, baseConfig); // 将baseConfig和devConfig合并为一个配置
  • 打包组件时采用的 webpack 配置写在 webpack.prod.config.js 中，内容如下：
const path = require('path');
const merge = require('webpack-merge');
const baseConfig = require('./webpack.base.js'); // 引用公共的配置
const MiniCssExtractPlugin = require("mini-css-extract-plugin"); // 用于将组件的css打包成单独的文件输出到`lib`目录中

const prodConfig = {
  mode: 'production', // 开发模式
  entry: path.join(__dirname, "../src/index.js"),
  output: {
    path: path.join(__dirname, "../lib/"),
    filename: "index.js",
    libraryTarget: 'umd', // 采用通用模块定义
    libraryExport: 'default', // 兼容 ES6 的模块系统、CommonJS 和 AMD 模块规范
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        loader: [MiniCssExtractPlugin.loader,'css-loader?modules'],
      },
    ]
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: "main.min.css" // 提取后的css的文件名
    })
  ],
  externals: { // 定义外部依赖，避免把react和react-dom打包进去
    react: {
      root: "React",
      commonjs2: "react",
      commonjs: "react",
      amd: "react"
    },
    "react-dom": {
      root: "ReactDOM",
      commonjs2: "react-dom",
      commonjs: "react-dom",
      amd: "react-dom"
    }
  },
};

module.exports = merge(prodConfig, baseConfig); // 将baseConfig和prodConfig合并为一个配置
  • 完成 webpack 配置文件的编写之后，需要在 package.json 中的scripts 字段中配置相关的启动、打包和发布命令，在 package.json 中添加的脚本内容如下：
// package.json
...
  "scripts": {
    "start": "webpack-dev-server --config config/webpack.dev.config.js", // 使用webpack-dev-server启动一个开发服务用于预览组件效果
    "build": "webpack --config config/webpack.prod.config.js", // 打包组件
    "pub": "npm run build && npm publish", // 打包组件并发布到npm
  },
...

配置 babel

  • 我们需要使用 babel 把我们的代码编译成 es5 版本。在项目根目录下建好的 .babelrc文件内补充以下内容：
{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}
  • 以上则完成了脚手架的搭建过程，接下来就可以开始开发组件。

开发组件

  • 为了演示，我将在 src 目录中创建一个简单的具有样式的组件，大家可根据自己的需要进行修改，index.js 文件的具体内容如下：
<!-- src/index.js -->
import React from 'react';
import * as styles from './index.css';
class ReactDemo extends React.Component{
  render () {
    return <div className={styles.wrapper}>hello world</div>
  }
}
export default ReactDemo;
  • 样式文件 index.css 文件的具体内容如下：
<!-- src/index.css -->
.wrapper{
  background: red;
}
  • 为了在开发时实时预览组件的效果，则需要在 example 目录下新建 index.html 和 app.js 两个文件， index.html 的内容如下：
<!-- examples/src/index.html -->
<html>
<head>
    <title>My First React Component</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
</head>
<body>
  <div id="root"></div>
  <script src="bundle.js"></script> <!-- 这句十分重要 -->
</body>
</html>
  • 细心的同学会⚠️注意⚠️到， index.html 文件中引入了文件名为 bundle.js 的脚本，原因是在开发过程（使用webpack-dev-sevrer启动开发服务）时，并不会实际在 src 目录下生成 bundle.js，打包好的文件是在内存中的，如果要实时预览效果，需要在 html 中引入（也可使用html-webpack-plugin插件注入，这里不进行具体讲解）。
  • app.js 的内容如下：
/*** examples/src/app.js ***/
import React from 'react'
import { render } from 'react-dom'
import ReactDemo from '../../src' // 引入组件

const App = () => <ReactDemo />
render(<App />, document.getElementById('root'))
  • 现在在根目录执行 npm start，当看到如下图的结果，则表示编译成功：
    编译成功结
  • 此时访问 127.0.0.1:3001则可以看到下图的结果：

组件打包及功能测试

  • 完成组件的开发，再发包之前，需要对自己的组件的功能进行打包和测试。

组件打包

  • 前面已经在 package.json 中添加了打包组件的命令，然而，在执行 npm run build 之前，还需要在 package.json 中修改 main 字段，作用是声明组件的入口文件。

开发者在 import 我们的组件的时候会引入main 字段中 export 的内容。

  • 截止到目前为止，我的 package.json 完整内容如下，为便于理解，我加上注释，如果要直接使用删掉注释即可：
{
  "name": "react-demo-component", // 发布的 npm 包的名字，确保独一无二（先在 npm 上搜，若与已有的包重名会报错）
  "version": "1.0.0", // npm 包版本
  "description": "A test component demo", // 包的描述
  "main": "lib/index.js", // *重点*：声明组件的入口文件
  "scripts": { // 执行脚本
    "start": "webpack-dev-server --config config/webpack.dev.config.js", // 使用webpack-dev-server启动一个开发服务用于预览组件效果
    "build": "webpack --config config/webpack.prod.config.js", // 打包组件
    "pub": "npm run build && npm publish", // 打包组件并发布到npm
  },
  "keywords": [ // 关键字（在npm网站上搜索 npm 包的关键词）
    "react",
    "hello world"
  ],
  "author": "feSmallBlack", // npm 包的作者
  "license": "ISC", // 版权许可证
  "devDependencies": { // 开发环境依赖
    "@babel/cli": "^7.5.5",
    "@babel/core": "^7.5.5",
    "@babel/preset-env": "^7.5.5",
    "@babel/preset-react": "^7.0.0",
    "babel-loader": "^8.0.6",
    "css-loader": "^3.2.0",
    "mini-css-extract-plugin": "^0.8.0",
    "react": "^16.9.0",
    "react-dom": "^16.9.0",
    "style-loader": "^1.0.0",
    "webpack": "^4.39.3",
    "webpack-cli": "^3.3.7",
    "webpack-dev-server": "^3.8.0",
    "webpack-merge": "^4.2.2"
  },
  "dependencies": {} 生产环境依赖
}
  • 接下来，则可以使用 npm run build 打包我们开发好的组件，出现下面的结果则代表打包成功：

打包成功的结果

  • 此时，项目根目录的 lib 目录下会出现以下两个文件：
    lib目录下的内容
  • 这两个文件则是我们要发布的包。

组件功能测试

  • 虽然跃跃欲试忍不住要发包，但是！在发包之前，为了对大家和自己负责，避免频繁的撤包操作，最好就是先对自己的组件进行试用。
  • 我们可以使用 npm link 把打包之后的组件引入到全局 node_modules 中，相关命令如下：
// At development directory
npm run build
npm link
  • 执行 npm link 命令后的结果如下：
    npm link的结果
  • 在 example/src/app.js 文件中进行试用，相关命令如下：
// At development directory
cd example/src
npm link react-demo-component
  • 然后修改 example/src/app.js 的内容：
/*** examples/src/app.js ***/
import React from 'react'
import { render } from 'react-dom'
import ReactDemo from 'react-demo-component';
import 'react-demo-component/lib/main.min.css'; // ！需要引入样式！
// import ReactDemo from '../../src'

const App = () => <ReactDemo />
render(<App />, document.getElementById('root'))
  • 出现下面的结果，则代表打包的组件功能验证通过：
    验证功能结果
  • 接下来将介绍喜闻乐见的最后一个环节，发布组件到 NPM！

发布组件

配置.npmignore

  • 如果项目中没有编写 .npmignore 文件，则需要在 package.json 中新增 files 字段，用于申明将要发布到 NPM 的文件。如果省略掉这一项，所有文件包括源代码会被一起上传到 NPM。
  • 本文采用写 .npmignore 文件的方式，实现仅发布打包后的组件代码。 .npmignore 文件的具体内容如下：
# 指定发布 npm 的时候需要忽略的文件和文件夹
# npm 默认不会把 node_modules 发上去
config # webpack配置
example # 开发时预览代码
src # 组件源代码目录
.babelrc # babel 配置

注册 npm 账号

  • 要发布一个 npm 包，我们需使用如下命令添加一个 npm 的账号（如果已经添加过的这一步可以跳过）：
npm adduser
  • 按提示信息输入自己的用户名、密码及邮箱后，如果命令行输出Logged in as <user> on https://registry.npmjs.org/，则说明账号注册并登陆成功。npm 会把登陆信息记录并暂存在 /Users/<user>/.npmrc 配置文件中。
  • 如果已经有 npm 账号，可以直接使用 npm login 登录。
  • ⚠️注意：由于国内使用 npm 官方源安装包的时候比较慢，基本上在国内开发都会修改 npm 源地址，在发包之前，一定要切换到 npm 源才可以，不然就会报出如下错误：
error: no_perms Private mode enable, only admin can publish this module
  • 可以使用npm config list查看当前使用的源地址，如果不是官方源地址，则可以通过下面的命令切换 npm 源：
npm config set registry http://registry.npmjs.org
  • 也可以使用 nrm 来进行 npm 的源管理，碍于本文篇幅，这里就不再进行解释（传送门👉：使用NRM进行NPM的源管理）
  • 成功切换到官方源后，则可以使用下面命令将我们的组件发布到 NPM：
npm run pub
// 上面的命令效果与下面的命令效果一样
npm build
npm publish
  • 当看到下面的结果，则表示发包成功：
    发包成功结果
  • 此时在 npm 上也可以查看你刚发布的包：
    npm结果
  • 别人也可以使用下面的命令下载你的包：
npm i react-demo-component // 假设你的包名字叫react-demo-component
  • 使用方法：
// 组件中引入
import ReactDemo from 'react-demo-component';
// 如果给组件写了样式，需要手动导入css文件
import 'react-demo-component/lib/main.min.css';
  • 取消发布（最好不要，别人可能下载了你的包）：
npm unpublish react-demo-component --force // 假设你的包名字叫react-demo-component
avatar
文章
阅读
粉丝