@haixing_hu/rollup-builder
v1.8.3
Published
An tool for creating multi-format JavaScript libraries with Rollup.
Downloads
144
Maintainers
Readme
Rollup Builder
rollup-builder
提供了一个工具函数,用于简化使用 Rollup 打包器构建 JavaScript 库的过程。
它允许您生成多种格式,如 CommonJS (CJS)、ES Module (ESM) 和 Universal Module
Definition (UMD) 格式,可以选择是否进行代码压缩。
目录
特性
- 以多种格式构建 JavaScript 库,使其在不同环境中通用。
- 轻松进行生产环境下的代码压缩。
- 自动生成用于调试的源映射。
- 使用简单的选项配置库的格式、文件名等。
- 您可以在 ESM(ES6 模块系统)模块中混合使用默认导出和命名导出, 并且 Rollup 将生成同时与 CommonJS 和 ES6 兼容的 CJS 或 UMD 格式代码。
- 支持通过 Rollup 插件和自定义配置高度定制。
安装
您可以将 rollup-builder
安装为开发依赖,使用 npm
或 yarn
安装:
npm install @haixing_hu/rollup-builder --save-dev
# 或
yarn add @haixing_hu/rollup-builder --dev
使用
创建一个 Rollup 配置文件(通常命名为
rollup.config.mjs
),并导出一个函数,该函数定义了库的构建选项。 您可以使用提供的rollupBuilder
函数来简化此过程。示例
rollup.config.mjs
:import rollupBuilder from '@haixing_hu/rollup-builder'; export default rollupBuilder('MyLibrary', import.meta.url);
自定义
rollup.config.mjs
文件,以满足库的特定要求。您可以指定输入文件、格式、文件名前缀和其他选项。 有关详细信息,请参阅 配置选项 部分。示例
rollup.config.mjs
:import rollupBuilder from '@haixing_hu/rollup-builder'; export default rollupBuilder('MyLibrary', import.meta.url, { formats: ['cjs', 'esm'], minify: true, // Customize additional options as needed. });
使用以下命令运行 Rollup 构建过程:
rollup -c rollup.config.mjs
构建后的库文件将位于
dist
目录中,遵循您指定的格式。例如,如果您指定了formats: ['cjs', 'esm']
, 将生成以下文件:dist/my-library.cjs.js dist/my-library.cjs.min.js dist/my-library.esm.mjs dist/my-library.esm.min.mjs
您应该修改
package.json
文件,以指定库的入口点。例如,如果您指定了formats: ['cjs', 'esm']
, 您应该将package.json
文件中的main
,module
和exports
字段设置为:{ "main": "dist/my-library.cjs.min.js", "module": "dist/my-library.esm.min.mjs", "exports": { ".": { "require": "./dist/my-library.cjs.min.js", "import": "./dist/my-library.esm.min.mjs" } } }
您应该将以下开发依赖项添加到您的库中:
yarn add --dev @babel/core @babel/plugin-transform-runtime @babel/preset-env \ @rollup/plugin-alias @rollup/plugin-babel @rollup/plugin-commonjs \ @rollup/plugin-node-resolve @rollup/plugin-terser rollup rollup-plugin-analyzer
或
npm install -D @babel/core @babel/plugin-transform-runtime @babel/preset-env \ @rollup/plugin-alias @rollup/plugin-babel @rollup/plugin-commonjs \ @rollup/plugin-node-resolve @rollup/plugin-terser rollup rollup-plugin-analyzer
配置选项
libraryName: string
:您的库的名称(在 UMD 格式中使用)。importMetaUrl: string
:调用者模块的import.meta.url
。options: object
:额外的构建选项,包括:debug: boolean
:是否启用调试模式。如果未指定此字段,默认值为false
。formats: [string]
:构建的格式数组。它可以是以下值的数组:'cjs'
: CommonJS 格式。'umd'
: UMD 格式。'esm'
: ES 模块格式。
['cjs', 'esm']
。exports: string
:要使用的导出模式。它可以是以下值之一:'auto'
:根据输入模块导出的内容自动猜测您的意图。'default'
:如果您只使用export default ...
导出一个事物;请注意,这可能在生成旨在与ESM输出互换的 CommonJS输出时引起问题。'named'
:如果您使用命名导出。'none'
:如果您没有导出任何东西(例如,您正在构建一个应用程序,而不是库)。'mixed'
:如果您使用命名导出与默认导出混合。请注意,这不是 Rollup 官方支持的标准导出模式,而是此库添加的附加模式。 有关更多详情,请参阅混合默认和命名导出。
'auto'
。nodeEnv: string
:NODE_ENV
环境变量。如果未指定此字段,默认值为process.env.NODE_ENV
。minify: boolean
:是否对代码进行压缩。如果未指定此字段,对于生产环境,默认值为true
,否则为false
。sourcemap: boolean
:是否生成源映射。如果未指定此字段,默认值为true
。input: string
:库的输入文件。如果未指定此字段,默认值为'src/index.js'
。outputDir: string
:库的输出目录。如果未指定此字段,默认值为'dist'
。filenamePrefix: string
:输出文件的前缀。如果未指定此字段,默认值为库名称的短横线形式。externals: [string]
:额外的外部包,每个可以通过字符串或正则表达式指定。如果未指定此字段,默认值为空数组。useAliasPlugin: boolean
:是否使用@rollup/plugin-alias
插件。如果未指定此字段,默认值为true
。aliasPluginOptions: object
:@rollup/plugin-alias
插件的选项。如果未指定此字段,默认值为:{ entries: { 'src': fileURLToPath(new URL('src', importMetaUrl)), }, }
useNodeResolvePlugin: boolean
:是否使用@rollup/plugin-node-resolve
插件。如果未指定此字段,默认值为true
。nodeResolvePluginOptions: object
:@rollup/plugin-node-resolve
插件的选项。如果未指定此字段,默认值为:{}
。useCommonjsPlugin: boolean
:是否使用@rollup/plugin-commonjs
插件。如果未指定此字段,默认值为true
。commonjsPluginOptions: object
:@rollup/plugin-commonjs
插件的选项。如果未指定此字段,默认值为:{ include: ['node_modules/**'], }
useBabelPlugin: boolean
:是否使用@rollup/plugin-babel
插件。如果未指定此字段,默认值为true
。babelPluginOptions: object
:@rollup/plugin-babel
插件的选项。如果未指定此字段,默认值为:
请注意,如果使用{ babelHelpers: 'runtime', exclude: ['node_modules/**'], presets: [ '@babel/preset-env', ], plugins: [ '@babel/plugin-transform-runtime', ], }
@rollup/plugin-babel
插件,您还可以在标准的 Babel 配置文件中指定 Babel 的配置,例如babel.config.js
、.babelrc
等。terserOptions: object
(对象):@rollup/plugin-terser
插件的选项。如果未指定此字段, 默认值为:{}
。是否使用@rollup/plugin-terser
插件取决于选项的minify
字段或NODE_ENV
环境变量。useAnalyzerPlugin: boolean
(布尔值):是否使用rollup-plugin-analyzer
插件。 如果未指定此字段,默认值为true
。analyzerOptions: object
(对象):rollup-plugin-analyzer
插件的选项。 如果未指定此字段,默认值为:{ hideDeps: true, limit: 0, summaryOnly: true, }
useVisualizerPlugin: boolean
:是否使用rollup-plugin-visualizer
插件。 如果未指定此字段,默认值为true
。visualizerPluginOptions: object
:rollup-plugin-visualizer
插件的选项。 如果未指定此字段,默认值为:
其中{ filename: './doc/${filenameBase}.visualization.html', gzipSize: true, brotliSize: true, }
filenameBase
是编译后的库文件在./dist
目录中的基本名称。plugins
(对象数组):额外的 Rollup 插件。如果未指定此字段,默认值为空数组。
混合默认导出和命名导出
如果一个 ESM(ES6 模块系统)模块同时具有默认导出和命名导出,Rollup 无法正确处理它。 例如,以下是一个 ESM 模块源码:
export { Foo, Bar };
export default Foo;
Rollup 会将其转换为以下代码:
exports.Foo = Foo;
exports.Bar = Bar;
exports.default = Foo;
然而,一个 CommonJS 代码模块通常会这样使用该模块:
const Foo = require('my-module');
这将导致一个错误。正确的用法应该是
const Foo = require('my-module').default
但不幸的是,Rollup 会将 ESM 默认导入转换为以下形式:
// 源代码
import Foo from 'my-module';
// 转换后
const Foo = require('my-module');
注意,上述转换没有 .default
后缀,这将导致错误。
如果您在 ESM 模块中同时使用默认导出和命名导出,Rollup 将生成下述警告消息:
(!) Mixing named and default exports
https://rollupjs.org/configuration-options/#output-exports
The following entry modules are using named and default exports together:
src/index.js
Consumers of your bundle will have to use chunk.default to access their default export, which may not be what you want. Use `output.exports: "named"` to disable this warning.
解决办法来自 Rollup 官方插件的源代码,为每个 CJS
格式的包添加一个简单的output.footer
:
module.exports = Object.assign(exports.default, exports);
这样 Rollup 会将混合输出转换为以下形式:
exports.Foo = Foo;
exports.Bar = Bar;
exports.default = Foo;
module.exports = Object.assign(exports.default, exports);
于是调用者可以直接使用下面方式引入默认导出:
const Foo = require('my-module');
// 或
import Foo from 'my-module';
有关更多详细信息,请参阅以下网页:
- Rollup Configuration Options: output.exports
- Issue #1961: Question regarding mixing default and named exports
- StackOverflow: Mixing default and named exports with Rollup
- Github Repository: rollup-patch-seamless-default-export
注意: 为了使用此特性,您必须在 rollup.config.mjs
文件中指定 exports: 'mixed'
选项,即:
import rollupBuilder from '@haixing_hu/rollup-builder';
export default rollupBuilder('MyLibrary', import.meta.url, { exports: 'mixed' });
贡献
欢迎贡献!如果您发现任何问题或有改进建议,请随时提出问题或创建拉取请求。
许可证
本项目根据 Apache 2.0 许可证进行许可。有关详细信息,请参阅 LICENSE 文件。