build-plugin-component

通过 build-scripts 和 build-plugin-component 支持业务组件（即 NPM 包）的开发，功能：

• 支持构建 ES5 + ES Module 产物，对应 es/，使用 babel 构建
• 支持构建 ES5 + Commonjs 产物，对应 lib/，使用 babel 构建
• 支持构建 UMD 产物，对应 dist/，使用 webpack 构建
• 支持使用 markdown 写 demo 同时构建文档产物，对应 build/，使用 webpack 构建

该方案同时支持 React 和 Rax 业务组件开发，如果是开发 Rax 组件请查阅 Rax 官方文档，本文档主要介绍 React 组件开发。

目录

• 创建组件
• 组件调试构建
• 组件目录
• 工程配置
• 版本升级
• 高阶用法

创建组件

通过命令行初始化一个业务组件项目：

# 安装全局 CLI
$ npm i -g iceworks
# 新建组件文件夹
$ mkdir my-component && cd my-component
# 初始化
$ iceworks init component

> 如果是阿里内部的同学并且想接入 DEF 发布 NPM 包，可以参考文档 组件开发接入 DEF

组件调试构建

$ cd my-component
$ npm install
$ npm start

# 实时编译 lib&es 产物
$ npm start -- --watch

# 实时编译 dist 产物
$ npm start -- --watch-dist

# 启动 https 服务
$ npm start -- --https

# 跳过 demo 构建
$ npm start -- --skip-demo
$ npm build -- --skip-demo

# 跳过自动打开预览链接
$ npm start -- --disable-open

组件目录

目录结构

├── src/                  # 组件源码
│  └── index.js
├── demo                  # 组件 demo
│  └── usage.md
├── lib/                  # 构建产物，编译为 ES5 + Commonjs 规范的代码
├── es/                   # 构建产物，编译为 ES5 + ES Module 规范的代码
├── dist/                 # 构建产物，UMD 相关产物，默认不生成，需要通过设置 library 参数开启
├── build/                # 构建产物，用于组件文档预览
├── build.json            # 工程配置
├── README.md
└── package.json

组件入口

组件入口文件为 src/index.tsx：

import React from 'react';

export default function ExampleComponent(props) {
  const { type, ...others } = props;
  return <>Hello;
}

样式文件

默认生成样式文件为 src/index.css，根据需求可调整成 sass 或 less 文件。

推荐在 src/index.tsx 中引入组件样式：

import React from 'react';
+ import './index.css';

export default function ExampleComponent(props) {}

组件 demo

组件的 demo 演示文件，位于 demo 目录下，使用 yaml-markdown 语法。可以通过修改默认的 usage.md 来调整组件 demo，或通过增加 example.md 文件来创建多个 demo。

每个 demo 的格式如下：

---
title: Simple Usage
order: 1
---

本 demo 演示一行文字的用法。

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import ExampleComponent from 'my-component';

function App() {
  return ;
}

ReactDOM.render(, mountNode);
```

组件文档

在执行 npm run build 时，会通过 demo/ 以及 README.md 生成 build/index.html，将 html 进行托管即可完整预览组件的文档。

以 @icedesign/qrcode 组件的文档为例，通过 unpkg 的服务即可查阅文档：文档地址 。

注意：构建 build 会加长 npm run build 的时间，如不需要可通过 --skip-demo 的命令行参数关闭。

工程配置

基于 build-scripts 的项目统一使用 build.json 作为工程配置的文件：

{
  "type": "react",
  "plugins": [["build-plugin-component"]]
}

通过 build-plugin-component 这个基础插件，我们支持了以下配置项：

alias

• 类型：object
• 默认值：{}

{
  "alias": {
    "@": "./src"
  }
}

babelPlugins

• 类型：array
• 默认值：[]

> 注意：该选项仅影响 es/lib 目录构建产物，如需要修改 demo 预览时的 babel 配置，请通过 webpack-chain 形式进行自定义。

devServer

• 类型：object
• 默认值：{ hot: true, disableHostCheck: true, clientLogLevel: 'silent' }

同 webpack devServer 配置，自定义配置将会与默认配置合并。

filename

• 类型： string
• 默认值：null

如果打包 library 到 dist 目录，用来配置打包文件的名字。

library

• 类型： string
• 默认值：null

如果打包 library 到 dist 目录，用来配置 library 名字。

libraryExport

• 类型： string
• 默认值：null

如果打包 library 到 dist 目录，用来配置 library 出口配型，如可配置 default，对应的组件出口为 export default MyComponent。

libraryTarget

• 类型： string
• 默认值：null

如果打包 library 到 dist 目录，用来配置 library 的类型，如 umd、amd 等。

sourceMap

• 类型： boolean
• 默认值：false

如果打包 library 到 dist 目录，用来配置是否产出 sourceMap 文件。

define

• 类型：object
• 默认：null

minify

• 类型：boolean
• 默认：false

如果打包 library 到 dist 目录，配置打包文件是否压缩。

generateTypesForJs

• 类型：boolean
• 默认值：false

htmlInjection

• 类型：object
• 默认值：{}

向 demo 预览的 html 里注入内容，比如插入一些静态脚本等：

{
  "htmlInjection": {
    "headAppend": [
      "