UNPKG

7.03 kBMarkdownView Raw
1[npm]: https://img.shields.io/npm/v/stan-builder
2[npm-url]: https://www.npmjs.com/package/stan-builder
3[download]: http://img.shields.io/npm/dm/stan-builder.svg?style=flat
4[test]: https://github.com/planjs/stan/actions/workflows/test.yml/badge.svg
5[size]: https://packagephobia.now.sh/badge?p=stan-builder
6[size-url]: https://packagephobia.now.sh/result?p=stan-builder
7
8[![npm][npm]][npm-url]
9[![size][size]][size-url]
10[![test][test]][test]
11[![NPM downloads][download]][npm-url]
12
13# `stan-builder`
14
15> 集成 `rollup` `babel` 常用打包配置.
16
17## Install
18
19Using npm:
20
21```console
22npm install stan-builder --save-dev
23```
24
25## Features
26* ✔︎ 支持 typeScript
27* ✔︎ 支持 cjs、esm、umd、systemjs 四种格式的打包
28* ✔︎ esm 支持生成 mjs，直接为浏览器使用
29* ✔︎ 支持 postcss
30* ✔︎ 支持打包成 node browser 用的代码
31
32## Usage
33
34```shell script
35# Bundle library
36stan-builder --esm --cjs --minify
37
38# Bundle dev
39stan-builder -w
40```
41
42## Config
43新建配置文件 `.stanrc.ts` `.stanrc.js` `.stanrc.tsx`
44```typescript
45// BundleOptions
46export default {
47 esm: true,
48 umd: true,
49 target: 'browser',
50}
51```
52
53### Bundle Options
54#### entry
55
56指定入口文件。
57
58* Type: `string`
59* Default：`src/index.js`
60
61默认会查找 `src/index.tsx`, `src/index.ts`, `src/index.jsx`, `src/index.js`, `src/index.vue`，如果存在，则会作为默认的 entry。如果库文件为 `typescript`，则需要在根目录配置`tsconfig.json`，否则会编译错误。
62`babel` 模式下是编译 `entry` 所在文件夹的所有文件。
63
64> 如果是 `vue` 默认使用的是 `vue3` `rollup-plugin-vue@6.x`, 如果是 `vue2` 请项目内安装 `rollup-plugin-vue@5.x`
65
66#### file
67
68指定输出文件名。
69
70* Type: `string`
71* Default：与 `entry` 相同的文件名，`entry.[umd|cjs|esm].[min].js` 默认自动增加后缀。
72
73> - `[esm|cjs|umd].file` 优先级比这个高，没有配置则默认这个。
74
75#### bundler
76
77打包工具。
78
79* Type: `rollup | babel`
80> - `umd` `systemjs` 规范只支持使用 `rollup`。
81
82#### runtimeHelpers
83
84是否把 helper 方法不打包引入 `@babel/runtime` 。
85
86> - 推荐开启，减少打包体积，公用项目内的 `runtime`。
87> - 开启 `runtimeHelpers`，一定要在 dependencies 里有 `@babel/runtime` 依赖
88> - `runtimeHelpers` 只对 esm 有效，cjs 下无效，因为 cjs 已经不给浏览器用了。
89
90#### minify
91
92是否压缩代码。
93
94* Type: `boolean`
95* Default: `false`
96
97> - 开启会自动生成`.min`后缀的文件。
98> - `css` 使用 `postcss`，`js` 使用 `terser`。
99> - `[esm|cjs|umd].minify` 优先级比这个高，没有配置则默认这个。
100
101#### extractCSS
102
103配置是否提取 css 为单独文件。
104
105* Type: `boolean`
106* Default: `false`
107
108#### injectCSS
109
110是否在 `<head>` 里注入css。
111
112* Type: `boolean`
113* Default: `true`
114
115#### sourcemap
116
117是否同步输出sourcemap。
118
119* Type: `boolean`
120* Default: `false`
121
122#### esm
123
124输出`esm`规范的代码。
125
126* Type：`"rollup" | "babel" | { type, file, mjs, bundler, minify, sourcemap, target, runtimeHelpers } | `boolean``
127
128#### cjs
129
130输出`cjs`规范的代码。
131
132* Type：`"rollup" | "babel" | { type, file, lazy, bundler, minify, sourcemap, target, runtimeHelpers } | `boolean``
133
134#### cjs.lazy
135
136是否开启 lazy require。
137
138* Type: `boolean`
139* Default: `false`
140
141> 可加速命令行执行速度，同时减少依赖和耦合。
142
143#### umd
144
145输出`umd`规范的代码。
146
147* Type： `"rollup" | "babel" | { type, file, name, global, bundler, minify, sourcemap, target, runtimeHelpers } | `boolean``
148
149#### umd.name
150
151指定 `rollup` 的 [name](https://rollupjs.org/guide/en/#output-name) 配置。
152
153* Type: `string`
154* Default：默认 camelCase packages.json 中的 `name`
155
156#### umd.global
157
158指定 `rollup` 的 [global](https://rollupjs.org/guide/en/#output-globals) 配置。
159
160* Type: `react=React,react-dom=ReactDom | { pkg: global name }`
161
162> - `external` 中的包默认会 camelCase 作为默认值。
163
164#### system
165
166输出`systemjs`规范的代码，默认使用`rollup`。
167
168* Type：`boolean`
169
170#### target
171
172配置是 node 库还是 browser 库，只作用于语法层。
173
174* Type: `"node" | "browser"`
175* Default: `"browser"`
176
177> - 如果 `entry` 后缀为 `.jsx|.tsx` 默认为 `browser`。
178
179#### extraBabelPlugins
180
181配置额外的 babel plugins。
182
183* Type: `array`
184* Default: `[]`
185
186#### extraBabelPresets
187
188配置额外的 babel preset。
189
190* Type: `array`
191* Default: `[]`
192
193#### extraExternals
194
195配置一些依赖走 externals。
196
197* Type: `array<string | RegExp>`
198* Default: []
199
200> * rollup 的 external 保留内部默认处理，新增 external
201> * 打包esm, cjs时 dependencies 和 peerDependencies 里的内容会被 external
202> * 打包umd时 peerDependencies 会被 external
203
204#### externalsExclude
205
206配置一些依赖不走 externals。
207
208* Type: `array<string | RegExp>`
209* Default: `[]`
210
211#### externalPeerDependenciesOnly
212
213只 externals `peerDependencies` 中的依赖。
214
215* Type: `string[]`
216* Default: `[]`
217
218#### extraPostCSSPlugins
219
220配置额外 postcss plugin
221
222* Type: `string[]`
223* Default: `[]`
224
225#### extraRollupPlugins
226
227配置额外 rollup plugin
228
229* Type: `array`
230* Default: `[]`
231
232#### analyze
233
234是否可视化展示打包的模块大小，使用 [rollup-plugin-visualizer](https://github.com/btd/rollup-plugin-visualizer) 。
235
236* Type: `boolean`
237* Default: `false`
238
239#### copy.targets
240
241是否打包同时复制文件。
242
243* Type: `{ src, dest, rename, transform } | array`
244* Default: `undefined`
245
246> - 这里使用 [globby](https://github.com/sindresorhus/globby) 匹配文件。
247> - 如果 watch 模式，匹配到的文件也会 watch 并且copy。
248
249#### copy.flatten
250
251是否复制的时候删除目录结构。
252
253* Type: `boolean`
254* Default: `true`
255
256#### rollup plugin options
257
258* `nodeResolveOpts`: [@rollup/plugin-node-resolve](https://github.com/rollup/plugins/blob/master/packages/node-resolve/README.md)
259* `replaceOpts`: [@rollup/plugin-replace](https://github.com/rollup/plugins/blob/master/packages/replace/README.md)
260* `commonjsOpts`: [@rollup/plugin-commonjs](https://github.com/rollup/plugins/blob/master/packages/commonjs/README.md)
261* `injectOpts`: [@rollup/plugin-inject](https://github.com/rollup/plugins/blob/master/packages/inject/README.md)
262* `terserOpts`: [rollup-plugin-terser](https://github.com/TrySound/rollup-plugin-terser)
263* `typescript2Opts`: [rollup-plugin-typescript2](https://github.com/ezolenko/rollup-plugin-typescript2)
264 > 如果项目内有 `typescript` 默认 `declaration: true`
265* `aliasOpts`: [@rollup/plugin-alias](https://github.com/rollup/plugins/blob/master/packages/alias/README.md)
266* `visualizerOpts`: [rollup-plugin-visualizer](https://github.com/btd/rollup-plugin-visualizer)
267* `postcssOpts`: [rollup-plugin-postcss](https://github.com/egoist/rollup-plugin-postcss#readme)
268
269> 如果是 ts 可以参考 `stan-builder/typings/types.d.ts` 中的 `BundleOptions`
270
271## Usage in node
272```js
273const builder = require('stan-builder');
274
275builder({
276 verbose: true
277}).then(() => {
278 console.log("Build complete.")
279})
280```