README
father
Library toolkit based on rollup and docz.
视频教程:利用 umi-library(father) 做组件打包。
Features
- ✔︎ 基于 docz 的文档功能
- ✔︎ 基于 rollup 和 babel 的组件打包功能
- ✔︎ 支持 TypeScript
- ✔︎ 支持 cjs、esm 和 umd 三种格式的打包
- ✔︎ esm 支持生成 mjs,直接为浏览器使用
- ✔︎ 支持用 babel 或 rollup 打包 cjs 和 esm
- ✔︎ 支持多 entry
- ✔︎ 支持 lerna
- ✔︎ 支持 css 和 less,支持开启 css modules
Installation
Install father
via yarn or npm.
$ yarn add father
Usage
# Bundle library
$ father build
# dev with doc
$ father doc dev
# build doc
$ father doc build
# deploy doc to github.io
$ father doc deploy
Cli
build
打包库,输出多种格式的文件。
# Normal build
$ father build
# Bundle src/foo.js with esm=rollup, cjs=rollup and umd, and specify the output filename with bar
$ father build --esm --cjs --umd --file bar src/foo.js
Success!
$ tree ./dist
./dist
- bar.js
- bar.esm.js
- bar.umd.js
- bar.umd.min.js
doc
doc 包含 dev 和 build 两个子命令。
$ father doc dev
$ father doc build
$ father doc deploy
所有的命令行参数会透传给 docz,详见 docz.site#project-configuration。
注:
- 不能传
--config
参数,通过--config
指定的文件内容可全部配置在.fatherrc.js
的 doc 配置里。 - 使用
deploy
之前请先执行build
命令,文档部署后域名为:https://yourname.github.io/your-repo
。
Config
新建 .fatherrc.js
文件进行配置。
比如:
export default {
entry: 'src/foo.js',
doc: {
themeConfig: { mode: 'dark' },
base: '/your-repo'
},
}
注意:
- lerna 项目可以为每个 package 单独配,并且可以继承根目录的
.fatherrc.js
配置 - 配置文件支持 es6 和 TypeScript
Options
entry
指定入口文件。
- Type:
string | string[]
- Default:
src/index.js
注:事实上,我们会依次找 src/index.tsx
, src/index.ts
, src/index.jsx
, src/index.js
,如果存在,则会作为默认的 entry。如果库文件为 typescript
,则需要在根目录配置tsconfig.json
,否则会编译错误。
file
指定输出文件。
- Type:
string
- Default: 与 entry 相同的文件名,esm 会加
.esm.js
后缀,umd 会加.umd[.min].js
后缀
注:
- entry 为数组时,不可配置 file,因为不能多个 entry 输出到同一个文件
- 为不同 entry 指定不同的输出文件名时,可通过 overridesByEntry 实现
esm
是否输出 esm 格式,以及指定 esm 格式的打包方式等。
- Type:
"rollup" | "babel" | { type, file, mjs } | false
- Default:
false
esm 为 rollup
或 babel
时,等同于配置了 { type: "rollup" | "babel" }
。
esm.type
指定 esm 的打包类型,可选 rollup
或 babel
。
- Type:
"rollup" | "babel"
- Default:
undefined
esm.file
指定 esm 的输出文件名。
- Type:
string
- Default:
undefined
esm.mjs
是否同时输出一份给浏览器用的 esm,以 .mjs
为后缀。
- Type:
boolean
- Default:
false
注:
- mjs 目前不通用,除非你知道这是什么,否则不要配置。
esm.minify
是否压缩 esm 格式。
- Type:
boolean
- Default:
false
通常不需要配置,除非你发布到 npm 的代码需要保密。
esm.importLibToEs
是否在 esm 模式下把 import 项里的 /lib/
转换为 /es/
。
- Type:
boolean
- Default:
false
比如 import 'foo/lib/button';
,在 cjs 模式下会保持原样,在 esm 模式下会编译成 import 'foo/es/button';
。
cjs
是否输出 cjs 格式,以及指定 cjs 格式的打包方式等。
- Type:
"rollup" | "babel" | { type, file } | false
- Default:
false
cjs 为 rollup
或 babel
时,等同于配置了 { type: "rollup" | "babel" }
。
cjs.type
指定 cjs 的打包类型,可选 rollup
或 babel
。
- Type:
"rollup" | "babel"
- Default:
undefined
cjs.file
指定 cjs 的输出文件名。
- Type:
string
- Default:
undefined
cjs.minify
是否压缩 cjs 格式。
- Type:
boolean
- Default:
false
通常不需要配置,除非你发布到 npm 的代码需要保密。
umd
是否输出 umd 格式,以及指定 umd 的相关配置。
- Type:
{ globals, name, minFile, file } | false
- Default:
false
umd.globals
指定 rollup 的 globals 配置。
umd.name
指定 rollup 的 name 配置。
- Type:
string
- Default:
${camelCase(basename(pkg.name))}
umd.minFile
是否为 umd 生成压缩后的版本。
- Type:
boolean
- Default:
false
umd.file
指定 umd 的输出文件名。
- Type:
string
- Default:
undefined
autoprefixer
配置参数传给 autoprefixer,详见 autoprefixer#options,常用的有 flexbox
和 browsers
。
比如:
export default {
autoprefixer: {
browsers: [
'ie>8',
'Safari >= 6',
],
},
}
cssModules
配置是否开启 css modules。
- Type:
boolean
- Default:
false
默认是 .module.css
走 css modules,.css
不走 css modules。配置 cssModules
为 true
后,全部 css 文件都走 css modules。(less 文件同理)
extractCSS
配置是否提取 css 为单独文件。
- Type:
boolean
- Default:
false
extraBabelPresets
配置额外的 babel preset。
- Type:
array
- Default:
[]
extraBabelPlugins
配置额外的 babel plugin。
- Type:
array
- Default:
[]
比如配置 babel-plugin-import 按需加载 antd,
export default {
extraBabelPlugins: [
['babel-plugin-import', {
libraryName: 'antd',
libraryDirectory: 'es',
style: true,
}],
],
};
extraPostCSSPlugins
配置额外的 postcss plugin。
- Type:
array
- Default:
[]
extraExternals
为 rollup 模式配置额外的 external,但不推荐这么做,external 可通过 dependencies 和 peerDependencies 的约定实现。
- Type:
string[]
- Default:
[]
namedExports
配置 rollup-plugin-commonjs 的 namedExports。
disableTypeCheck
是否禁用类型检测。
- Type:
boolean
- Default:
false
target
配置是 node 库还是 browser 库,只作用于语法层。
- Type:
"node" | "browser"
- Default:
"browser"
如果为 node
,兼容到 node@6;如果为 browser
,兼容到 ['last 2 versions', 'IE 10']
,所以肯定会是 es5 的语法。
browserFiles
target 为 node
时,配置例外文件走 browser
target。
- Type:
[string]
- Default:
[]
nodeFiles
target 为 browser
时,配置例外文件走 node
target。
- Type:
[string]
- Default:
[]
runtimeHelpers
是否把 helper 方法提取到 @babel/runtime
里。
- Type:
boolean
- Default:
false
注:
- 推荐开启,能节约不少尺寸
- 配置了
runtimeHelpers
,一定要在 dependencies 里有@babel/runtime
依赖 - runtimeHelpers 只对 esm 有效,cjs 下无效,因为 cjs 已经不给浏览器用了,只在 ssr 时会用到,无需关心小的尺寸差异
replace
配置需要替换的内容,基于 rollup-plugin-replace。
- Type:
Object
- Default:
{}
注:
- babel 模式下暂不支持
- 如果要输出字符串,值的部分用
JSON.stringify()
转下
比如:
export default {
replace: {
VERSION: JSON.stringify(require('./package').version),
},
},
overridesByEntry
根据 entry 覆盖配置。
比如要为不同的 entry 配置不同的输出文件名,
export default {
entry: ['foo.js', 'bar.js'],
overridesByEntry: {
'foo.js': {
file: 'bar',
},
'bar.js': {
file: 'foo',
},
},
}
overridesByEntry 里的配置会和外面的配置进行 shadow 合并,比如:
export default {
umd: { globals: { jquery: 'window.jQuery' } }
entry: ['foo.js', 'bar.js'],
overridesByEntry: {
'foo.js': {
umd: { name: 'foo' },
},
},
}
则 foo.js
的 umd 配置为 { globals: { jquery: 'window.jQuery' }, name: 'foo' }
。
doc
透传配置给 docz,可以有 title
、theme
、themeConfig
等。
比如要切换默认主题为 dark 模式:
export default {
doc: { themeConfig: { mode: 'dark' } },
}
doc.htmlContext
此配置在 docz 中没有标明,但是却是支持的,可用于扩展 html 模板。
export default {
doc: {
htmlContext: {
head: {
favicon: '',
meta: [],
links: [
{ rel: 'stylesheet', href: 'foo.css' },
],
scripts: [
{ src: 'bar.js' },
],
},
body: {
scripts: [
{ src: 'hoo.js' },
],
},
},
}
};
Bonus
一些小贴士:
- 通常只要配置
esm: "rollup"
就够了 - cjs 和 esm 支持 rollup 和 babel 两种打包方式,rollup 是跟进 entry 把项目依赖打包在一起输出一个文件,babel 是把 src 目录转化成 lib(cjs) 或 es(esm)
- 如果要考虑 ssr,再配上
cjs: "rollup"
package.json
里配上sideEffects: false | string[]
,会让 webpack 的 tree-shaking 更高效
关于 dependencies、peerDependencies 和 external
- cjs 和 esm 格式打包方式选 rollup 时有个约定,dependencies 和 peerDependencies 里的内容会被 external
- esm.mjs 和 umd 格式,只有 peerDenendencies 会被 external
- 打包方式 babel 时无需考虑 external,因为是文件到文件的编译,不处理文件合并
关于 babel 模式
babel 模式下一些文件不会被编译到 es 和 lib 下,包含:
- mdx 文件
- 测试文件,比如 test.js、spec.js、e2e.js,后缀还支持 jsx、ts 和 tsx
环境变量
LERNA
LERNA=none
时强制不走 lerna 方式的构建。
PACKAGE
lerna 模式下,指定 package 只构建一个,调试时用于提效。
# 只构建 packages/foo
$ PACKAGE=foo father build
LICENSE
MIT