阅读 2778

使用npm发布一个react组件(踩坑实践)

前言

  • 本文主要记录本人在使用 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-loadercss-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,
    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 -->
<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,当看到如下图的结果,则表示编译成功:
    编译成功结
  • 此时访问 localhost:3001则可以看到下图的结果:
    localhost结果

组件打包及功能测试

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

组件打包

  • 前面已经在 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
复制代码
关注下面的标签,发现更多相似文章
评论