本文主要记录本人在使用 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.htmlapp.js 两个文件, index.html 的内容如下:
  • <!-- examples/src/index.html -->
        <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>
      <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 打包我们开发好的组件,出现下面的结果则代表打包成功:
  • 虽然跃跃欲试忍不住要发包,但是!在发包之前,为了对大家和自己负责,避免频繁的撤包操作,最好就是先对自己的组件进行试用。
  • 我们可以使用 npm link 把打包之后的组件引入到全局 node_modules 中,相关命令如下:
  • // At development directory
    npm run build
    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 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
    
  • 如果你想学习关于 vue 组件的发包,好文传送👉你可以写一个自己的npm包
  • 源码地址:github.com/chongtianHo…
  • 以上则是全文的介绍内容,相关配置均经过本人呕心沥血的亲身实践,如有问题欢迎留言。
  • 分类:
    前端
    标签: