@x-configs/rollup

A Rollup helper for defining configs when bundling packages.

Install

npm i -D @x-configs/rollup

Usage

function defineJsConfig(pkg: PackageJson, opts?: JsOptions): RollupOptions;
function defineDtsConfig(pkg: PackageJson, opts?: DtsOptions): RollupOptions;

type JsOptions = {
    /**
     * The root directory to output.
     */
    dest?: string;
    /**
     * The bundle's entry points (e.g. your main.js or app.js or index.js).
     * @default 'src/index.ts'
     * @see {@link https://rollupjs.org/configuration-options/#input }
     */
    input?: string;
    /**
     * @see {@link https://rollupjs.org/configuration-options/#output-name }
     */
    output?: {
        /**
         * Necessary for iife/umd bundles that exports values in which case it is the global variable name representing your bundle.
         * Other scripts on the same page can use this variable name to access the exports of your bundle.
         * @see {@link https://rollupjs.org/configuration-options/#name }
         */
        name?: string;
        /**
         * If `true`, a separate sourcemap file will be created.
         * If `"inline"`, the sourcemap will be appended to the resulting `output` file as a data URI.
         * If `"hidden"` works like `true` except that the corresponding sourcemap comments in the bundled files are suppressed.
         * @see {@link https://rollupjs.org/configuration-options/#output-sourcemap }
         */
        sourcemap?: boolean | 'inline' | 'hidden';
        /**
         * By default, sourcemap files generated by Rollup uses relative URLs to reference the files they describe.
         * By providing an absolute base URL, e.g. `https://example.com`, sourcemaps will use absolute URLs instead.
         * @see {@link https://rollupjs.org/configuration-options/#output-sourcemapbaseurl }
         */
        sourcemapBaseUrl?: string;
        /**
         * What export mode to use. Defaults to `auto`, which guesses your intentions based on what the `input` module exports.
         * @default 'auto'
         * @see {@link https://rollupjs.org/configuration-options/#output-exports }
         */
        exports?: OutputOptions['exports'];
        /**
         * This will minify the wrapper code generated by rollup. Note that this does not affect code written by the user. This option is useful when bundling pre-minified code.
         * @see {@link https://rollupjs.org/configuration-options/#output-compact }
         */
        compact?: boolean;
        /**
         * Whether to extend the global variable defined by the `name` option in `umd` or `iife` formats.
         * When `true`, the global variable will be defined as (`global.name = global.name || {}`).
         * When `true`, the global defined by `name` will be overwritten like (`global.name = {}`).
         * @see {@link https://rollupjs.org/configuration-options/#output-extend }
         */
        extend?: boolean;
        /**
         * Re-parses each generated chunk to detect if the generated code is valid JavaScript.
         * This can be useful to debug output generated by plugins that use the `renderChunk` hook to transform code.
         * @see {@link https://rollupjs.org/configuration-options/#output-validate }
         */
        validate?: boolean;
        /**
         * Which language features Rollup can safely use in generated code.
         * This will not transpile any user code but only change the code Rollup uses in wrappers and helpers.
         *
         * @see {@link https://rollupjs.org/configuration-options/#output-generatedcode }
         */
        generatedCode?: OutputOptions['generatedCode'];
        /**
         * A string to `prepend` to the bundle.
         * You can also supply a function that returns a Promise that resolves to a string to generate it asynchronously (Note: `banner` and `footer` options will not break sourcemaps)
         * @see {@link https://rollupjs.org/configuration-options/#output-banner-output-footer }
         */
        banner?: OutputOptions['banner'];
        /**
         * A string to `append` to the bundle.
         * You can also supply a function that returns a Promise that resolves to a string to generate it asynchronously (Note: `banner` and `footer` options will not break sourcemaps)
         * @see {@link https://rollupjs.org/configuration-options/#output-banner-output-footer }
         */
        footer?: OutputOptions['footer'];
        /**
         * Similar to `output.banner`, except that the code goes inside any format-specific wrapper.
         * @see {@link https://rollupjs.org/configuration-options/#output-intro-output-outro }
         */
        intro?: OutputOptions['intro'];
        /**
         * Similar to `output.footer`, except that the code goes inside any format-specific wrapper.
         * @see {@link https://rollupjs.org/configuration-options/#output-intro-output-outro }
         */
        outro?: OutputOptions['outro'];
        /**
         * Specifies id: variableName pairs necessary for external imports in umd/iife bundles.
         * @see {@link https://rollupjs.org/configuration-options/#output-globals }
         */
        globals?: OutputOptions['globals'];
    };
    /**
     * Specifies the format of the generated bundle: `cjs`, `esm`, `iife`, `umd`
     * @see {@link https://rollupjs.org/configuration-options/#output-format }
     */
    formats?: {
        cjs?: boolean;
        esm?: boolean;
        iife?: boolean;
        umd?: boolean;
    };
    /**
     * Which language features Rollup can safely use in generated code.
     * This will not transpile any user code but only change the code Rollup uses in wrappers and helpers.
     *
     * @default
     * { arrowFunctions: true, constBindings: true }
     *
     * @see {@link https://rollupjs.org/configuration-options/#output-generatedcode }
     */
    generatedCode?: 'es5' | 'es2015' | {
        /**
         * Whether to use arrow functions for auto-generated code snippets.
         * Note that in certain places like module wrappers, Rollup will keep using regular functions wrapped in parentheses as in some JavaScript engines, these will provide noticeably better performance.
         * @see {@link https://rollupjs.org/configuration-options/#output-generatedcode-arrowfunctions }
         */
        arrowFunctions?: boolean;
        /**
         * This will use `const` instead of `å` in certain places and helper functions.
         * This will allow Rollup to generate more efficient helpers due to block scoping.
         * @see {@link https://rollupjs.org/configuration-options/#output-generatedcode-constbindings }
         */
        constBindings?: boolean;
        /**
         * Allows the use of shorthand notation in objects when the property name matches the value.
         * @see {@link https://rollupjs.org/configuration-options/#output-generatedcode-objectshorthand }
         */
        objectShorthand?: boolean;
        /**
         * Determine whether reserved words like "default" can be used as prop names without using quotes.
         * This will make the syntax of the generated code ES3 compliant.
         * Note however that for full ES3 compliance, you may also need to polyfill some builtin functions like `Object.keys` or `Array.prototype.forEach`.
         * @default true
         * @see {@link https://rollupjs.org/configuration-options/#output-generatedcode-reservednamesasprops }
         */
        reservedNamesAsProps?: boolean;
        /**
         * Allows choosing one of the presets listed above while overriding some options.
         * @see {@link https://rollupjs.org/configuration-options/#output-generatedcode-preset }
         */
        preset?: 'es5' | 'es2015';
        /**
         * Whether to allow the use of `Symbol` in auto-generated code snippets.
         * Currently, this only controls if namespaces will have the `Symbol.toStringTag` property set to the correct value of Module, which means that for a namespace, `String(namespace)` logs `[object Module]`. This again is used for feature detection in certain libraries and frameworks.
         * @see {@link https://rollupjs.org/configuration-options/#output-generatedcode-symbols }
         */
        symbols?: boolean;
    };
    /**
     * Either a function that takes an id and returns true (external) or true (not external), or an Array of module IDs, or regular expressions to match module IDs, that should remain external to the bundle. Can also be just a single ID or regular expression.
     * @see {@link https://rollupjs.org/configuration-options/#external }
     */
    external?: ExternalOption;
    /**
     * Specifies id: variableName pairs necessary for external imports in umd/iife bundles.
     * @see {@link https://rollupjs.org/configuration-options/#output-globals }
     */
    globals?: OutputOptions['globals'];
    /**
     * Path to the tsconfig path to use
     * @default './tsconfig.json'
     */
    tsconfig?: string;
    plugins?: {
        /**
         * A Rollup plugin for seamless integration between Rollup and Typescript.
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-typescript#options }
         */
        typescript?: RollupTypescriptOptions;
        /**
         * A Rollup plugin which replaces targeted strings in files while bundling.
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-replace#options }
         */
        replace?: RollupReplaceOptions;
        /**
         * A Rollup plugin to convert CommonJS modules to ES6, so they can be included in a Rollup bundle
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-commonjs#options }
         */
        commonjs?: boolean | RollupCommonJSOptions;
        /**
         * A Rollup plugin which locates modules using the `Node resolution algorithm`, for using third party modules in node_modules
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-node-resolve#options }
         */
        nodeResolve?: RollupNodeResolveOptions;
        /**
         * A Rollup plugin which Converts .json files to ES6 modules.
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-json#options }
         */
        json?: boolean | RollupJsonOptions;
        /**
         * A Rollup plugin to generate a minified bundle with terser.
         * The plugin accepts a terser Options object as input parameter, to modify the default behaviour.
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-terser#options }
         * @see {@link https://github.com/terser/terser#minify-options }
         * @see {@link https://terser.org/docs/options/ }
         */
        terser?: boolean | Options;
        /**
         * A Rollup plugin for defining aliases when bundling packages.
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-alias#options }
         */
        alias?: RollupAliasOptions;
        /**
         * A Rollup plugin to remove debugger statements and functions like assert.equal and console.log from your code.
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-strip#options }
         */
        strip?: boolean | RollupStripOptions;
    };
};
/**
 * DtsOptions
 */
type DtsOptions = {
    /**
     * The root directory to output.
     */
    dest?: string;
    /**
     * The entry file
     * @default 'src/index.ts'
     */
    input?: string;
    /**
     * The `dts` file to output
     * @default pkg.types || pkg.exports?.types || 'lib/index.d.ts'
     */
    output?: string;
    /**
     * Either a function that takes an id and returns true (external) or true (not external), or an Array of module IDs, or regular expressions to match module IDs, that should remain external to the bundle. Can also be just a single ID or regular expression.
     * @see {@link https://rollupjs.org/configuration-options/#external }
     */
    external?: ExternalOption;
    plugins?: {
        /**
         * This is a plugin that lets you roll-up your `.d.ts` definition files.
         * @see {@link https://www.npmjs.com/package/rollup-plugin-dts }
         */
        dts?: Options$1;
        /**
         * A Rollup plugin which replaces targeted strings in files while bundling.
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-replace#options }
         */
        replace?: RollupReplaceOptions;
        /**
         * A Rollup plugin for defining aliases when bundling packages.
         * @see {@link https://www.npmjs.com/package/@rollup/plugin-alias#options }
         */
        alias?: RollupAliasOptions;
    };
};

Examples

import { env } from 'node:process';
import { readFileSync } from 'node:fs';
import { defineJsConfig, defineDtsConfig } from '@x-configs/rollup';

const pkgJson = JSON.parse(readFileSync('./package.json', 'utf-8'));
const isDevEnv = /^dev/i.test(env.NODE_ENV);

const input = 'src/index.ts';
const dest = isDevEnv ? `../../dev/${pkgJson.name}` : `../../prod/${pkgJson.name}`;

// plugins
const plugins = {
  terser: isDevEnv
    ? false
    : {
        compress: {
          ecma: 2022,
        },
        mangle: {},
        format: {
          comments: 'some',
        },
      },
};

const configs = [
  defineJsConfig(pkgJson, {
    dest,
    input,
    output: {
      sourcemap: isDevEnv,
    },
    plugins,
  }),

  defineDtsConfig(pkgJson, {
    input,
    output: 'lib/index.d.ts',
    dest,
  }),
];

export default configs;