1 | # @huzan/hz-lib
|
2 |
|
3 | ## 安装
|
4 |
|
5 | ```bash
|
6 | npm install @huzan/hz-lib -g
|
7 | npm install @huzan/hz-lib
|
8 |
|
9 | ```
|
10 |
|
11 | ## Config
|
12 |
|
13 | 根目录下新建 `.local.hzrc.lib.js` 本地配置文件进行配置(不要上传 git)。
|
14 |
|
15 | 比如:
|
16 |
|
17 | ```js
|
18 | module.exports = {
|
19 | runLibs: ['@huzan/hz-dialog'], //每次要跑的项目(优先使用)
|
20 | }
|
21 | ```
|
22 |
|
23 | 新建 `.hzrc.lib.js` 文件进行配置。
|
24 |
|
25 | 比如:
|
26 |
|
27 | ```js
|
28 | export default {
|
29 | entry: ['src/index.js'],
|
30 | cjs: 'rollup',
|
31 | esm: 'rollup',
|
32 | runtimeHelpers: true,
|
33 | packagesPatterns: ['packages/*'],
|
34 | }
|
35 | ```
|
36 |
|
37 | ### Options
|
38 |
|
39 | #### entry
|
40 |
|
41 | 指定入口文件。
|
42 |
|
43 | - Type: `string | string[]`
|
44 | - Default:`src/index.js`
|
45 |
|
46 | 注:事实上,我们会依次找 `src/index.tsx`, `src/index.ts`, `src/index.jsx`, `src/index.js`,如果存在,则会作为默认的 entry。如果库文件为 `typescript`,则需要在根目录配置`tsconfig.json`,否则会编译错误。
|
47 |
|
48 | #### file
|
49 |
|
50 | 指定输出文件。
|
51 |
|
52 | - Type: `string`
|
53 | - Default: 与 entry 相同的文件名,esm 会加 `.esm.js` 后缀,umd 会加 `.umd[.min].js` 后缀
|
54 |
|
55 | 注:
|
56 |
|
57 | 1. entry 为数组时,不可配置 file,因为不能多个 entry 输出到同一个文件
|
58 | 2. 为不同 entry 指定不同的输出文件名时,可通过 [overridesByEntry](#overridesbyentry) 实现
|
59 |
|
60 | #### esm
|
61 |
|
62 | 是否输出 esm 格式,以及指定 esm 格式的打包方式等。
|
63 |
|
64 | - Type: `"rollup" | "babel" | { type, file, mjs } | false`
|
65 | - Default: `false`
|
66 |
|
67 | esm 为 `rollup` 或 `babel` 时,等同于配置了 `{ type: "rollup" | "babel" }`。
|
68 |
|
69 | #### esm.type
|
70 |
|
71 | 指定 esm 的打包类型,可选 `rollup` 或 `babel`。
|
72 |
|
73 | - Type: `"rollup" | "babel"`
|
74 | - Default: `undefined`
|
75 |
|
76 | #### esm.file
|
77 |
|
78 | 指定 esm 的输出文件名。
|
79 |
|
80 | - Type: `string`
|
81 | - Default: `undefined`
|
82 |
|
83 | #### esm.mjs
|
84 |
|
85 | 是否同时输出一份给浏览器用的 esm,以 `.mjs` 为后缀。
|
86 |
|
87 | - Type: `boolean`
|
88 | - Default: `false`
|
89 |
|
90 | 注:
|
91 |
|
92 | 1. mjs 目前不通用,除非你知道这是什么,否则不要配置。
|
93 |
|
94 | #### esm.minify
|
95 |
|
96 | 是否压缩 esm 格式。
|
97 |
|
98 | - Type: `boolean`
|
99 | - Default: `false`
|
100 |
|
101 | 通常不需要配置,除非你发布到 npm 的代码需要保密。
|
102 |
|
103 | #### cjs
|
104 |
|
105 | 是否输出 cjs 格式,以及指定 cjs 格式的打包方式等。
|
106 |
|
107 | - Type: `"rollup" | "babel" | { type, file } | false`
|
108 | - Default: `false`
|
109 |
|
110 | cjs 为 `rollup` 或 `babel` 时,等同于配置了 `{ type: "rollup" | "babel" }`。
|
111 |
|
112 | #### cjs.type
|
113 |
|
114 | 指定 cjs 的打包类型,可选 `rollup` 或 `babel`。
|
115 |
|
116 | - Type: `"rollup" | "babel"`
|
117 | - Default: `undefined`
|
118 |
|
119 | #### cjs.file
|
120 |
|
121 | 指定 cjs 的输出文件名。
|
122 |
|
123 | - Type: `string`
|
124 | - Default: `undefined`
|
125 |
|
126 | #### cjs.minify
|
127 |
|
128 | 是否压缩 cjs 格式。
|
129 |
|
130 | - Type: `boolean`
|
131 | - Default: `false`
|
132 |
|
133 | 通常不需要配置,除非你发布到 npm 的代码需要保密。
|
134 |
|
135 | #### umd
|
136 |
|
137 | 是否输出 umd 格式,以及指定 umd 的相关配置。
|
138 |
|
139 | - Type: `{ globals, name, minFile, file } | false`
|
140 | - Default: `false`
|
141 |
|
142 | #### umd.globals
|
143 |
|
144 | 指定 rollup 的 [globals](https://rollupjs.org/guide/en#output-globals) 配置。
|
145 |
|
146 | #### umd.name
|
147 |
|
148 | 指定 rollup 的 [name](https://rollupjs.org/guide/en#output-name) 配置。
|
149 |
|
150 | - Type: `string`
|
151 | - Default: `${camelCase(basename(pkg.name))}`
|
152 |
|
153 | #### umd.minFile
|
154 |
|
155 | 是否为 umd 生成压缩后的版本。
|
156 |
|
157 | - Type: `boolean`
|
158 | - Default: `false`
|
159 |
|
160 | #### umd.file
|
161 |
|
162 | 指定 umd 的输出文件名。
|
163 |
|
164 | - Type: `string`
|
165 | - Default: `undefined`
|
166 |
|
167 | #### autoprefixer
|
168 |
|
169 | 配置参数传给 autoprefixer,详见 [autoprefixer#options](https://github.com/postcss/autoprefixer#options),常用的有 `flexbox` 和 `browsers`。
|
170 |
|
171 | 比如:
|
172 |
|
173 | ```js
|
174 | export default {
|
175 | autoprefixer: {
|
176 | browsers: ['ie>8', 'Safari >= 6'],
|
177 | },
|
178 | }
|
179 | ```
|
180 |
|
181 | #### cssModules
|
182 |
|
183 | 配置是否开启 css modules。
|
184 |
|
185 | - Type: `boolean`
|
186 | - Default: `false`
|
187 |
|
188 | 默认是 `.module.css` 走 css modules,`.css` 不走 css modules。配置 `cssModules` 为 `true` 后,全部 css 文件都走 css modules。(less 文件同理)
|
189 |
|
190 | #### extraBabelPresets
|
191 |
|
192 | 配置额外的 babel preset。
|
193 |
|
194 | - Type: `array`
|
195 | - Default: `[]`
|
196 |
|
197 | #### extraBabelPlugins
|
198 |
|
199 | 配置额外的 babel plugin。
|
200 |
|
201 | - Type: `array`
|
202 | - Default: `[]`
|
203 |
|
204 | 比如配置 babel-plugin-import 按需加载 antd,
|
205 |
|
206 | ```js
|
207 | export default {
|
208 | extraBabelPlugins: [
|
209 | [
|
210 | 'babel-plugin-import',
|
211 | {
|
212 | libraryName: 'antd',
|
213 | libraryDirectory: 'es',
|
214 | style: true,
|
215 | },
|
216 | ],
|
217 | ],
|
218 | }
|
219 | ```
|
220 |
|
221 | #### extraPostCSSPlugins
|
222 |
|
223 | 配置额外的 postcss plugin。
|
224 |
|
225 | - Type: `array`
|
226 | - Default: `[]`
|
227 |
|
228 | #### namedExports
|
229 |
|
230 | 配置 rollup-plugin-commonjs 的 [namedExports](https://github.com/rollup/rollup-plugin-commonjs#usage)。
|
231 |
|
232 | #### target
|
233 |
|
234 | 配置是 node 库还是 browser 库,只作用于语法层。
|
235 |
|
236 | - Type: `"node" | "browser"`
|
237 | - Default: `"browser"`
|
238 |
|
239 | 如果为 `node`,兼容到 node@6;如果为 `browser`,兼容到 `['last 2 versions', 'IE 10']`,所以肯定会是 es5 的语法。
|
240 |
|
241 | #### runtimeHelpers
|
242 |
|
243 | 是否把 helper 方法提取到 `@babel/runtime` 里。
|
244 |
|
245 | - Type: `boolean`
|
246 | - Default: `false`
|
247 |
|
248 | 注:
|
249 |
|
250 | 1. 推荐开启,能节约不少尺寸
|
251 | 2. 配置了 `runtimeHelpers`,一定要在 dependencies 里有 `@babel/runtime` 依赖
|
252 | 3. runtimeHelpers 只对 esm 有效,cjs 下无效,因为 cjs 已经不给浏览器用了,只在 ssr 时会用到,无需关心小的尺寸差异
|
253 |
|
254 | #### replace
|
255 |
|
256 | 配置需要替换的内容,基于 [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace)。
|
257 |
|
258 | - Type: `Object`
|
259 | - Default: `{}`
|
260 |
|
261 | 注:
|
262 |
|
263 | 1. babel 模式下暂不支持
|
264 | 2. 如果要输出字符串,值的部分用 `JSON.stringify()` 转下
|
265 |
|
266 | 比如:
|
267 |
|
268 | ```js
|
269 | export default {
|
270 | replace: {
|
271 | VERSION: JSON.stringify(require('./package').version),
|
272 | },
|
273 | },
|
274 | ```
|
275 |
|
276 | #### overridesByEntry
|
277 |
|
278 | 根据 entry 覆盖配置。
|
279 |
|
280 | 比如要为不同的 entry 配置不同的输出文件名,
|
281 |
|
282 | ```js
|
283 | export default {
|
284 | entry: ['foo.js', 'bar.js'],
|
285 | overridesByEntry: {
|
286 | 'foo.js': {
|
287 | file: 'bar',
|
288 | },
|
289 | 'bar.js': {
|
290 | file: 'foo',
|
291 | },
|
292 | },
|
293 | }
|
294 | ```
|
295 |
|
296 | overridesByEntry 里的配置会和外面的配置进行 shadow 合并,比如:
|
297 |
|
298 | ```js
|
299 | export default {
|
300 | umd: { globals: { jquery: 'window.jQuery' } }
|
301 | entry: ['foo.js', 'bar.js'],
|
302 | overridesByEntry: {
|
303 | 'foo.js': {
|
304 | umd: { name: 'foo' },
|
305 | },
|
306 | },
|
307 | }
|
308 | ```
|
309 |
|
310 | 则 `foo.js` 的 umd 配置为 `{ globals: { jquery: 'window.jQuery' }, name: 'foo' }`。
|
311 |
|
312 | ## Bonus
|
313 |
|
314 | 一些小贴士:
|
315 |
|
316 | 1. 通常只要配置 `esm: "rollup"` 就够了
|
317 | 2. cjs 和 esm 支持 rollup 和 babel 两种打包方式,rollup 是跟进 entry 把项目依赖打包在一起输出一个文件,babel 是把 src 目录转化成 lib(cjs) 或 es(esm)
|
318 | 3. 如果要考虑 ssr,再配上 `cjs: "rollup"`
|
319 | 4. `package.json` 里配上 `sideEffects: false | string[]`,会让 webpack 的 [tree-shaking](https://webpack.js.org/guides/tree-shaking/) 更高效
|
320 |
|
321 | ### 关于 dependencies、peerDependencies 和 external
|
322 |
|
323 | 1. cjs 和 esm 格式打包方式选 rollup 时有个约定,dependencies 和 peerDependencies 里的内容会被 external
|
324 | 2. esm.mjs 和 umd 格式,只有 peerDenendencies 会被 external
|
325 | 3. 打包方式 babel 时无需考虑 external,因为是文件到文件的编译,不处理文件合并
|
326 |
|
327 | ### 关于 babel 模式
|
328 |
|
329 | babel 模式下一些文件不会被编译到 es 和 lib 下,包含:
|
330 |
|
331 | - mdx 文件
|
332 | - 测试文件,比如 test.js、spec.js、e2e.js,后缀还支持 jsx、ts 和 tsx
|
333 |
|
334 | ## License
|
335 |
|
336 | MIT © [LeoHuiyi](https://github.com/LeoHuiyi)
|