npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@haixing_hu/rollup-builder

v1.8.3

Published

An tool for creating multi-format JavaScript libraries with Rollup.

Downloads

144

Readme

Rollup Builder

npm package License English Document CircleCI

rollup-builder 提供了一个工具函数,用于简化使用 Rollup 打包器构建 JavaScript 库的过程。 它允许您生成多种格式,如 CommonJS (CJS)、ES Module (ESM) 和 Universal Module Definition (UMD) 格式,可以选择是否进行代码压缩。

目录

特性

  • 以多种格式构建 JavaScript 库,使其在不同环境中通用。
  • 轻松进行生产环境下的代码压缩。
  • 自动生成用于调试的源映射。
  • 使用简单的选项配置库的格式、文件名等。
  • 您可以在 ESM(ES6 模块系统)模块中混合使用默认导出和命名导出, 并且 Rollup 将生成同时与 CommonJS 和 ES6 兼容的 CJS 或 UMD 格式代码。
  • 支持通过 Rollup 插件和自定义配置高度定制。

安装

您可以将 rollup-builder 安装为开发依赖,使用 npmyarn 安装:

npm install @haixing_hu/rollup-builder --save-dev
# 或
yarn add @haixing_hu/rollup-builder --dev

使用

  1. 创建一个 Rollup 配置文件(通常命名为 rollup.config.mjs),并导出一个函数,该函数定义了库的构建选项。 您可以使用提供的 rollupBuilder 函数来简化此过程。

    示例 rollup.config.mjs

    import rollupBuilder from '@haixing_hu/rollup-builder';
    
    export default rollupBuilder('MyLibrary', import.meta.url);
  2. 自定义 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.
    });
  3. 使用以下命令运行 Rollup 构建过程:

    rollup -c rollup.config.mjs
  4. 构建后的库文件将位于 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
  5. 您应该修改 package.json 文件,以指定库的入口点。例如,如果您指定了 formats: ['cjs', 'esm'], 您应该将 package.json 文件中的 main, moduleexports 字段设置为:

    {
      "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"
          }
      }
    }
  6. 您应该将以下开发依赖项添加到您的库中:

    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: stringNODE_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: objectrollup-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.config.mjs 文件中指定 exports: 'mixed' 选项,即:

import rollupBuilder from '@haixing_hu/rollup-builder';

export default rollupBuilder('MyLibrary', import.meta.url, { exports: 'mixed' });

贡献

欢迎贡献!如果您发现任何问题或有改进建议,请随时提出问题或创建拉取请求。

许可证

本项目根据 Apache 2.0 许可证进行许可。有关详细信息,请参阅 LICENSE 文件。