如何从零开源一个React组件

有没有遇到这样一种情况,你花了很大精力在业务项目中写了一个组件,你觉得这个组件很通用,除了当前的业务场景还应该有其他的应用场景,所以你想开源这个组件,但又不知道从何入手。这篇文章就来聊聊如何开源一个前端组件,无论是业务中已有的组件还是新的组件。

1. 初始化

1.1 Git

可以在 Github 上新建一个项目,这里取名 "component-example",然后使用 git clone 命令克隆到本地进行开发。也可以先在本地建好文件,然后使用 git remote add 命令将本地项目与远程项目进行绑定。

1.2 NPM

进入项目根目录,执行 npm init 命令初始化项目,这里没什么注意点,一路默认即可,命令执行结束后会得到一个 "package.json" 文件。

1.3 React

在项目根目录新增 "src" 文件夹,进入 "src",新建 "index.js"、"index.css"、"App.js" 和 "App.css" 4 个文件。

"index.js"

import React from 'react';
import ReactDOM from 'react-dom';
import styles from './index.css';
import App from './App';

ReactDOM.render(<App />, document.getElementById('root'));

"APP.js"

import React from 'react';
import styles from './App.css';

export default class APP extends React.Component {
    render() {
        return <div>Hello, React Component!</div>
    }
}

安装 react 和 react-dom:

npm install --save react react-dom

2. 构建

2.1 Webpack

这里使用 webpack 作为打包构建工具。执行下面命令安装 webpack:

npm install --save webpack webpack-cli

新建 "webpack.common.js"、"webpack.dev.js" 和 "webpack.prod.js" 3 个文件,用于配置 webpack。因为开发环境和生产环境的需要不一样,比如开发环境需要 source map 以便快速定位问题,而生产环境需要文件尽量小以减少网络加载时间,所以需要维护两套不同的构建配置。虽然是两套配置,但仍然有很多配置是相同的,所以将相同的配置抽成 "webpack.common.js" 文件,开发环境特有的配置放在 "webpack.dev.js",生产环境特有的配置放在 "webpack.prod.js" 中。

"webpack.common.js"

const path = require("path");

module.exports = {
  entry: "./src/index.js",
  output: {
    path: path.resolve(__dirname, "dist"),
    filename: "component-example.js",
    libraryTarget: "umd"
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        loader: "style-loader!css-loader?modules"
      },
      {
        test: /\.(jpg|png)$/,
        loader: "url-loader?limit=25000"
      }
    ]
  },
  resolve: {
    extensions: [".jsx", ".js"]
  },
  plugins: []
};

"webpack.dev.js"

const merge = require("webpack-merge");
const common = require("./webpack.common.js");

module.exports = merge(common, {
  mode: "development",
  devtool: "inline-source-map",
  watch: true
});

"webpack.prod.js"

const merge = require("webpack-merge");
const common = require("./webpack.common.js");

module.exports = merge(common, {
  mode: "production",
  externals: ["react", "react-dom"]
});

上面的配置中用到了 style-loadercss-loaderurl-loaderwebpack-merge,也需要安装一下:

npm install --save-dev css-loader style-loader url-loader webpack-merge

"webpack.common.js" 中,output 的 path 和 filename 指定构建结果存在 /dist/component-example.js 中;libraryTarget 的值为 umd,这条配置必不可少,表明将 component-example.js 文件暴露为所有模块定义下都能运行的方式,即可以被当做 CommonJS 模块、 AMD 模块等不同类型的模块,从而可以在不同环境下运行。

另外,在 "webpack.common.js" 中还引入了 3 个 loader: style-loadercss-loaderurl-loader,前两者帮助 webpack 预处理样式文件,这里指 CSS 文件;url-loader 用于将本地文件处理成 base64,一般用于引用背景图时,如果没有需要,也可以删除。

"webpack.dev.js" 中有 3 个额外的配置。

  • mode: 代表构建模式,有 developmentproduction 两个值可选,不同的值会触发 webpack 不同的 Plugin,比如 development 会触发 NamedChunksPlugin,可以将 chunk id 变成字符串标识符,而 production 则会触发 UglifyJsPlugin,可以 uglify 代码;
  • devtool:代表是否生成以及如何生成 source map,这里使用了 inline-source-map,source map 会转换为 DataUrl 后添加到 bundle 中,因此 bundle 会变得很大,但毕竟开发环境并且仅仅是个组件项目,大小可控;
  • watch:可以监听文件变化,文件修改后可以自动重新编译。

"webpack.prod.js" 中除了 mode,还有 externals 配置项,表示构建的 bundle 中排除对 react 和 react-dom 的依赖,因为是 React 组件,用到该组件的地方肯定同时也引用了 react 和 react-dom,所以没必要再在组件的 bundle 中引入,这样又可以大大减少构建完的文件大小。

2.2 Babel

Babel 可以让我们使用 ES6 写 JS,所以我们也需要为项目添加 Babel 配置。

新建 ".babelrc" 文件,输入配置:

{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}

"webpack.common.js" 中添加 babel 相关的 配置:

rules: [
    {
    test: /\.(js|jsx)$/,
    exclude: /node_modules/,
    use: {
        loader: "babel-loader"
    }
  }
]

需要安装:

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

2.3 package.json

在 "package.json" 文件中根据 webpack 的 output 配置指定项目的入口文件,另外添加两条命令,分别是开发时启动命令和生产构建命令。

"main": "./dist/component-example.js",
"scripts": {
    "start": "webpack --config webpack.dev.js --progress --colors",
    "build": "webpack --config webpack.prod.js",
}

3. 调试

3.1 npm link

既然是组件,那便需要放入到一个完整的项目中去调试,这里使用 npm link

首先需要进入刚刚的组件根目录,执行 pwd,获取组件的绝对路径,然后进入一个完整的目标项目的根目录,执行 npm link $path ,"$path" 指的是刚刚执行 pwd 后获取到的路径 ,这样在目标项目的 "node_modules" 中创建了一个指向组件的软链接,相当于在目标文件中执行了 npm install --save component-example,只不过任何在 "component-example" 中的修改都会立即反馈到目标项目中。

npm link 还有一种方式,即在 "component-example" 根目录直接执行 npm link,那么会在全局的 node_modules 中创建名为 component-example 的 NPM 包,然后在目标项目中执行 npm link component-example 以引用组件文件。但这种方式会污染全局,一般不建议这么做。

引入组件后,可以像正常 NPM 包一样 import 和使用:

import ComponentExample from 'component-example';

export default class FullProject extends React.Component {
  render() {
    return <ComponentExample />;
  }
}

在组件项目中启动 npm start,任何更改可以自动构建,变化也会随时反馈到目标项目中。

开发结束后,记得在目标项目中解除 link:npm unlink component-example

3.2 CSS Modules

既然是前端组件,那 CSS 必不可少,如何引入 CSS 文件呢?这里使用 CSS Modules。任何一个 CSS 样式规则都是全局的,CSS Modules 的思路就是产生一个唯一的哈希字符串表示当前的规则,从而避免全局污染的情况。

那怎么使用呢?webpack 的 css-loader 便可以支持 CSS Modules,并且配置和使用起来都很方便。如果留意的话,你可能会发现 "webpack.common.js" 中引入 css-loader 时在后面添加了个参数: modules,这样便可以打开 CSS Modules 功能。

"App.css"

.title {
    color: red;
}

"App.js"

import React from 'react';
import styles from './App.css';

export default class APP extends React.Component {
    render() {
        return <div className={styles.title}>Hello, React Component!</div>
    }
}

JS 文件引入 CSS 模块,并命名为 styles, JSX 通过 className={styles.title} 声明类名。

4. 发布

经过一番编码调试,组件终于可以发布了,使用 npm run build 命令对项目进行构建,如果打开 "./dist/component-example.js" 的话,你会发现代码与开发时有很大差别。再执行 npm publish 将组件发布到 NPM 上。

使用 npm publish 时有几个注意点,首先你需要注册 NPM 账号,没有的话需要执行 npm adduser,注册完毕后登录 npm login,执行 npm who am i 验证是否已经成功登录,然后就可以愉快地 npm publish 了。另外一个注意点是每次发布时需要更新 "package.json" 中的 version,执行 npm version *.*.* 指定当前发布的版本,一定要大于上一次。

上面讲了如何从零开源一个 React 组件,只是从技术角度出发,开源过程中还会涉及其他的方方面面,这里不再详述。

发布于 2019-07-15

文章被以下专栏收录