{"id":23171440,"url":"https://github.com/haixing-hu/rollup-builder","last_synced_at":"2025-08-18T07:32:05.397Z","repository":{"id":203240976,"uuid":"709127172","full_name":"Haixing-Hu/rollup-builder","owner":"Haixing-Hu","description":"An tool for creating multi-format JavaScript libraries with Rollup.","archived":false,"fork":false,"pushed_at":"2025-06-30T08:32:49.000Z","size":1343,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-08T21:23:35.316Z","etag":null,"topics":["3rd-part","javascript","library","rollup"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Haixing-Hu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-24T04:19:55.000Z","updated_at":"2025-06-30T08:32:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"8bb9ebec-5e53-4a2d-86f3-b029792a91e3","html_url":"https://github.com/Haixing-Hu/rollup-builder","commit_stats":null,"previous_names":["haixing-hu/rollup-builder"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/Haixing-Hu/rollup-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haixing-Hu%2Frollup-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haixing-Hu%2Frollup-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haixing-Hu%2Frollup-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haixing-Hu%2Frollup-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Haixing-Hu","download_url":"https://codeload.github.com/Haixing-Hu/rollup-builder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haixing-Hu%2Frollup-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270961671,"owners_count":24675914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3rd-part","javascript","library","rollup"],"created_at":"2024-12-18T04:17:44.984Z","updated_at":"2025-08-18T07:32:05.378Z","avatar_url":"https://github.com/Haixing-Hu.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rollup Builder\n\n[![npm package](https://img.shields.io/npm/v/@qubit-ltd/rollup-builder.svg)](https://npmjs.com/package/@qubit-ltd/rollup-builder)\n[![License](https://img.shields.io/badge/License-Apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n[![中文文档](https://img.shields.io/badge/文档-中文版-blue.svg)](README.zh_CN.md)\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/Haixing-Hu/rollup-builder/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/Haixing-Hu/rollup-builder/tree/master)\n\n`rollup-builder` provides a utility function to simplify the process of building \nJavaScript libraries using the [Rollup] bundler. It allows you to generate various \nformats such as CommonJS (CJS), ES Module (ESM), and Universal Module Definition\n(UMD), and gives you the option to choose whether to perform code minification.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration Options](#configuration)\n- [Mixing Default and Named Exports](#mix-default-named)\n- [Contributions](#contributions)\n- [License](#license)\n\n## \u003cspan id=\"features\"\u003eFeatures\u003c/span\u003e\n\n- Build JavaScript libraries in multiple formats, making them compatible with a \n  variety of environments.\n- Minify your library for production use with ease.\n- Automatic generation of sourcemaps for debugging.\n- Configure the library's format, filename, and more using simple options.\n- You can [mix default and named exports](#mix-default-named) in ESM modules and \n  the [Rollup] will generate code in CJS or UMD format that compatible with both\n  CommonJS and ES6.\n- Highly customizable using [Rollup] plugins and custom configurations.\n\n## \u003cspan id=\"installation\"\u003eInstallation\u003c/span\u003e\n\nYou can install `rollup-builder` as a development dependency using `npm` or `yarn`:\n\n```bash\nnpm install @qubit-ltd/rollup-builder --save-dev\n# or\nyarn add @qubit-ltd/rollup-builder --dev\n```\n\n## \u003cspan id=\"usage\"\u003eUsage\u003c/span\u003e\n\n1. Create a [Rollup] configuration file (usually named `rollup.config.mjs`) and \n   export a function that defines the library's build options. You can use the \n   provided `rollupBuilder` function to streamline this process.\n\n   Example `rollup.config.mjs`:\n\n   ```js\n   import rollupBuilder from '@qubit-ltd/rollup-builder';\n\n   export default rollupBuilder('MyLibrary', import.meta.url);\n   ```\n\n2. Customize the `rollup.config.mjs` file to match your library's specific \n   requirements. You can specify the input file, formats, filename prefix, and \n   other options. Refer to the [Configuration Options](#configuration) section\n   for more details.\n\n   Example `rollup.config.mjs`:\n    \n   ```js\n   import rollupBuilder from '@qubit-ltd/rollup-builder';\n    \n   export default rollupBuilder('MyLibrary', import.meta.url, {\n     formats: ['cjs', 'esm'],\n     minify: true,\n     // Customize additional options as needed.\n   });\n   ```\n\n3. Run the [Rollup] build process using the following command:\n\n   ```bash\n   rollup -c rollup.config.mjs\n   ```\n\n4. The resulting library files will be placed in the `dist` directory, following \n   the format you specified. For example, if you specified `formats: ['cjs', 'esm']`,\n   the following files will be generated:\n   ```bash\n    dist/my-library.cjs.js\n    dist/my-library.cjs.min.js\n    dist/my-library.esm.mjs\n    dist/my-library.esm.min.mjs\n   ```\n   \n5. You should modify your `package.json` file to specify the entry point of your\n   library. For example, if you specified `formats: ['cjs', 'esm']`, you should\n   add the following lines to your `package.json` file:\n   ```json\n   {\n     \"main\": \"dist/my-library.cjs.min.js\",\n     \"module\": \"dist/my-library.esm.min.mjs\",\n     \"exports\": {\n         \".\": {\n            \"require\": \"./dist/my-library.cjs.min.js\",\n            \"import\": \"./dist/my-library.esm.min.mjs\"\n         }\n     }\n   }\n   ``` \n6. You should add the following dev dependencies to your library:\n   ```bash\n   yarn add --dev @babel/core @babel/plugin-transform-runtime @babel/preset-env \\\n     @rollup/plugin-alias @rollup/plugin-babel @rollup/plugin-commonjs \\\n     @rollup/plugin-node-resolve @rollup/plugin-terser rollup rollup-plugin-analyzer\n   ```\n   or \n   ```bash\n   npm install -D @babel/core @babel/plugin-transform-runtime @babel/preset-env \\\n     @rollup/plugin-alias @rollup/plugin-babel @rollup/plugin-commonjs \\\n     @rollup/plugin-node-resolve @rollup/plugin-terser rollup rollup-plugin-analyzer\n   ```\n\n## \u003cspan id=\"configuration\"\u003eConfiguration Options\u003c/span\u003e\n\n- `libraryName: string`: The name of your library (used in the UMD format).\n- `importMetaUrl: string`: The `import.meta.url` of the caller module.\n- `options: object`: Additional build options, including:\n    - `debug: boolean`: Whether to print debug information. If this field is not\n      specified, the default value is `false`.\n    - `formats: [string]`: An array of formats to build. It can be an array \n      of the following values:\n        - `'cjs'`: the CommonJS format.\n        - `'umd'`: the UMD format.\n        - `'esm'`: the ES module format.\n      \n      If this field is not specified, the default value is `['cjs', 'esm']`.\n    - `exports: string`: the export mode to use. It can be one of the following\n      values:\n        - `'auto'`: automatically guesses your intentions based on what the \n          input module exports.\n        - `'default'`: if you are only exporting one thing using\n          `export default ...`; note that this can cause issues when generating \n          CommonJS output that is meant to be interchangeable with ESM output.\n        - `'named'`: if you are using named exports.\n        - `'none'`: if you are not exporting anything (e.g. you are building an\n          app, not a library)\n        - `'mixed'`: if you are using named exports mixed with a default export.\n          Note that this is not a standard exports mode officially supported by\n          [Rollup], instead, it is an additional mode add by this library.\n          Refer to the [Mixing Default and Named Exports](#mix-default-named) for\n          more details.\n      \n      If this field is not specified, the default value is `'auto'`.\n    - `nodeEnv: string`: The `NODE_ENV` environment variable. If this field is \n      not specified, the default value is `process.env.NODE_ENV`.\n    - `minify: boolean`: Whether to minify the code. If this field is not \n      specified, the default value will be `true` for production environment, \n      and `false` otherwise.\n    - `sourcemap: boolean`: Whether to generate sourcemaps. If this field is not\n      specified, the default value is `true`.\n    - `input: string`: The input file of the library. If this field is not\n      specified, the default value is `src/index.js`.\n    - `outputDir: string`: The output directory of the library. If this field \n      is not specified, the default value is `dist`.\n    - `filenamePrefix: string`: The prefix for the output filename. If this \n      field is not specified, the default value the dash-case of the library \n      name.\n    - `externals: [string]`: the additional external packages, each can be \n      specified with either a string or a regular expression. If this field is\n      not specified, the default value is an empty array.\n    - `useAliasPlugin: boolean`: whether to use the `@rollup/plugin-alias` \n      plugin. If this field is not specified, the default value is `true`.\n    - `aliasPluginOptions: object`: the options for the `@rollup/plugin-alias` \n      plugin. If this field is not specified, the default value is:\n      ```js\n      {\n        entries: {\n          'src': fileURLToPath(new URL('src', importMetaUrl)),\n        },\n      }\n      ```\n    - `useNodeResolvePlugin: boolean`: whether to use the `@rollup/plugin-node-resolve`\n      plugin. If this field is not specified, the default value is `true`.\n    - `nodeResolvePluginOptions: object`: the options for the `@rollup/plugin-node-resolve`\n      plugin. If this field is not specified, the default value is: `{}`.\n    - `useCommonjsPlugin: boolean`: whether to use the `@rollup/plugin-commonjs` plugin.\n      If this field is not specified, the default value is `true`.\n    - `commonjsPluginOptions: object`: the options for the `@rollup/plugin-commonjs`\n      plugin. If this field is not specified, the default value is:\n      ```js\n      {\n        include: ['node_modules/**']\n      }\n      ```\n    - `useBabelPlugin: boolean`: whether to use the `@rollup/plugin-babel` plugin.\n      If this field is not specified, the default value is `true`.\n    - `babelPluginOptions: object`: the options for the `@rollup/plugin-babel` plugin.\n      If this field is not specified, the default value is:\n      ```js\n      {\n        babelHelpers: 'runtime',\n        exclude: ['node_modules/**'],\n        presets: [\n          '@babel/preset-env',\n        ],\n        plugins: [\n          '@babel/plugin-transform-runtime',\n        ]\n      }\n      ```\n      Note that if use the `@rollup/plugin-babel` plugin, you can also specify\n      the configuration of Babel in the standard Babel configuration files,\n      such as `babel.config.js`, `.babelrc`, etc.\n    - `terserOptions: object`: the options for the `@rollup/plugin-terser` plugin.\n      If this field is not specified, the default value is: `{}`. Whether\n      to use the `@rollup/plugin-terser` plugin depends on the `minify`\n      field of the options or the `NODE_ENV` environment variable.\n    - `useAnalyzerPlugin: boolean`: whether to use the `rollup-plugin-analyzer` plugin.\n      If this field is not specified, the default value is `true`.\n    - `analyzerOptions: object`: the options for the `rollup-plugin-analyzer` plugin.\n      If this field is not specified, the default value is:\n      ```js\n      {\n        hideDeps: true,\n        limit: 0,\n        summaryOnly: true,\n      }\n      ```\n    - `useVisualizerPlugin: boolean`: whether to use the `rollup-plugin-visualizer` plugin.\n      If this field is not specified, the default value is `true`.\n    - `visualizerPluginOptions: object`: the options for the `rollup-plugin-visualizer` plugin.\n      If this field is not specified, the default value is:\n      ```js\n      {\n        filename: './doc/${filenameBase}.visualization.html',\n        gzipSize: true,\n        brotliSize: true,\n      }\n      ```\n      where the `filenameBase` is the basename of the compiled library file in the\n      `./dist` directory.\n    - `plugins: [object]`: the additional [Rollup] plugins. If this field is not\n      specified, the default value is an empty array.\n\n## \u003cspan id=\"mix-default-named\"\u003eMixing Default and Named Exports\u003c/span\u003e\n\nIf an ESM module has both default export and named exports, [Rollup] cannot\nhandle it correctly. For example, the following is a source ESM module:\n```js\nexport { Foo, Bar };\nexport default Foo;\n```\nThe rollup will translate it into the following codes:\n```js\nexports.Foo = Foo;\nexports.Bar = Bar;\nexports.default = Foo;\n```\nHowever, a common-js consumer will use the module as follows:\n```js\nconst Foo = require('my-module');\n```\nwhich will cause an error. The correct usage should be\n```js\nconst Foo = require('my-module').default\n```\nBut unfortunately, [Rollup] will translate the ESM default import as follows:\n```js\n// source\nimport Foo from 'my-module';\n\n// translated\nconst Foo = require('my-module');\n```\nNote that the above translation has no `.default` suffix, which will cause an error.\n\nIf you mix default and named exports in an ESM module, [Rollup] will generate\na warning message as follows:\n```bash\n(!) Mixing named and default exports\nhttps://rollupjs.org/configuration-options/#output-exports\nThe following entry modules are using named and default exports together:\nsrc/index.js\n\nConsumers 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.\n```\n\nThe workaround is copied from the [source code of the official rollup plugins].\nIt makes the rollup option `output.exports` to `'named'` and adds a simple footer \nstatements to each `CJS` format bundle:\n```js\nmodule.exports = Object.assign(exports.default, exports);\n```\nWith this workaround, [Rollup] will transform mixed exports into the following form:\n```js\nexports.Foo = Foo;\nexports.Bar = Bar;\nexports.default = Foo;\nmodule.exports = Object.assign(exports.default, exports);\n```\nThus, the caller can directly use the following methods to import the default export:\n```js\nconst Foo = require('my-module');\n// or\nimport Foo from 'my-module';\n```\n\nSee the following web pages for more details:\n- [Rollup Configuration Options: output.exports]\n- [Issue #1961: Question regarding mixing default and named exports]\n- [StackOverflow: Mixing default and named exports with Rollup]\n- [Github Repository: rollup-patch-seamless-default-export]\n\n**NOTE:** In order to use this feature, you must specify the `exports` option to\n`'mixed'` in the `rollup.config.mjs` file, i.e.,\n```js\nimport rollupBuilder from '@qubit-ltd/rollup-builder';\n\nexport default rollupBuilder('MyLibrary', import.meta.url, { exports: 'mixed' });\n```\n\n## \u003cspan id=\"contributions\"\u003eContributions\u003c/span\u003e\n\nContributions are welcome! If you find any issues or have suggestions for\nimprovements, please feel free to open an issue or create a pull request.\n\n## \u003cspan id=\"license\"\u003eLicense\u003c/span\u003e\n\nThis project is licensed under the Apache 2.0 License. \nSee the [LICENSE](LICENSE) file for details.\n\n\n[Rollup]: https://rollupjs.org/\n[source code of the official rollup plugins]: https://github.com/rollup/plugins/blob/master/shared/rollup.config.mjs\n[Rollup Configuration Options: output.exports]: https://rollupjs.org/configuration-options/#output-exports\n[Issue #1961: Question regarding mixing default and named exports]: https://github.com/rollup/rollup/issues/1961\n[StackOverflow: Mixing default and named exports with Rollup]: https://stackoverflow.com/questions/58246998/mixing-default-and-named-exports-with-rollup\n[Github Repository: rollup-patch-seamless-default-export]: https://github.com/avisek/rollup-patch-seamless-default-export\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaixing-hu%2Frollup-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaixing-hu%2Frollup-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaixing-hu%2Frollup-builder/lists"}