Have ideas to improve npm?Join in the discussion! »

    bundlib
    TypeScript icon, indicating that this package has built-in type declarations

    0.18.4 • Public • Published

    Bundlib

    CircleCI npm codecov dependencies dev dependencies packagephobia types Known Vulnerabilities license

    An automatic library bundler powered by Rollup.js.

    ⚠️ Bundlib is under development, please file a new issue if you find any issue or bug, suggestions are welcome as well.

    In this guide

    Install

    npm i -D bundlib

    Build

    Bundlib will try to find your entry point file in the src folder. You can manually set your entry points using the input option.

    CommonJS module

    To build a CommonJS Module simply add a "main" field to your package.json pointing to the output file, see the configuration section for extra options.

    ES module

    To build a ES Module add a "module" field to your package.json pointing to the output file, see the configuration section for extra options.

    IIFE, AMD and UMD build

    For IIFE, AMD or UMD builds, add a "browser" field to your package.json. The default format is "umd" but it can be changed to "iife" or "amd" using the format option, see the configuration section for more info and extra options.

    Configuration

    Automatic Configuration

    Bundlib will configure Rollup according to you package.json data, see Advanced Configuration for more information.

    "main"

    The "main" field will be used as your CommonJS module output, if not present, CommonJS Module build will be skipped. You can skip the build manually using the skip option.

    "module" or "jsnext:main"

    The "module" field will be used as your ES Module output, if not present, ES Module build will be skipped. You can skip the build manually using the skip option. "jsnext:main" field will also be honored if "module" field is not present, but it is recommended to use the "module" field.

    "browser"

    The "browser" field will be used as your Browser build output, if not present, Browser build will be skipped. You can skip the build manually using the skip option. Bundlib only supports string type "browser" field, it will throw otherwise.

    "bin"

    The "bin" field will be used as your Binary build output, if not present, Binary build will be skipped. You can skip the build manually using the skip option. Bundlib only supports string type "bin" field, it will throw otherwise.

    "types" or "typings"

    The "types" field will be used as your Types output if you are using typescript. You can skip types generation using the skip option. "typings" field will also be honored if "types" field is not present.

    "dependencies"

    The "dependencies" field will be used to detect installed packages, it will also be used to set external dependencies for your CommonJS module, ES module, and Binary builds, for Browser build dependencies will be bundled into the output file unless otherwise specified using the "globals" option.

    "devDependencies"

    The "devDependencies" field will be used to detect installed packages.

    "peerDependencies"

    The "peerDependencies" field will be used as external dependencies for your CommonJS module,, ES module, and Binary builds.

    "bundlib"

    The "bundlib" field can be used for advanced configuration, see Advanced Configuration for more information.

    Advanced Configuration

    Advanced configuration can be done using the "bundlib" field in your package.json or by using one of the supported configuration files.

    Configuration in package.json

    Set "bundlib" field in your package.json to an object with your configuration. See options for more information.

    example

    // package.json
    {
      "name": "my-lib",
      "version": "1.0.0",
      "browser" : "dist/my-lib.amd.js",
      "bundlib": {
        "format": "amd"
      }
      ...
    }

    You can also set "bundlib" field in package.json to a string as a path, relative to the project root, pointing to a .json, .yaml, .yml or .js configuration file.

    example

    // package.json
    {
      "name": "my-lib",
      "version": "1.0.0",
      "browser" : "dist/my-lib.amd.js",
      "bundlib": "custom-options.yaml"
      // ...
    }

    then...

    # custom-options.yaml
    format: amd

    Configuration files

    If "bundlib" field not present in your package.json, Bundlib will try to find your configuration file using the following order...

    • .bundlibrc (json or yaml format)
    • .bundlibrc.json
    • .bundlibrc.yaml
    • .bundlibrc.yml
    • .bundlibrc.js
    • bundlib.config.js

    See the list of options below.

    Options

    The option object may contain any of the following properties. Any invalid or unknown option will cause Bundlib to throw at build time. Any option or sub-option set to null will be ignored.

    input

    input: string | SelectiveOption;

    The path to the files to be used as entry points for each of your builds.

    This option supports object based selective format. See Selective Options for more information.

    sourcemap

    sourcemap: boolean | 'inline' | 'hidden' | SelectiveOption;
    
    default true;

    Whether or not to generate source maps, See Rollup documentation for more information. If not specified or set to null it will default to true.

    This option supports object based and string based selective format. See Selective Options for more information.

    esModule

    esModule: boolean | SelectiveOption;
    
    default false;

    Whether or not to add a __esModule: true property to your module. If esModule = true it will affect all builds.

    This option supports object based and string based selective format. See Selective Options for more information.

    interop

    interop: boolean | SelectiveOption;
    
    default false;

    Whether or not to add an interop block. If interop = true it will affect all builds.

    This option supports object based and string based selective format. See Selective Options for more information.

    chunks

    chunks: Record<string, string>;

    A map of chunks to be built as CommonJS modules. The object key represents the input file and the value represents the output file, relative to the project root.

    Files created using this option won't be bundled into the CommonJS and Binary builds and will be imported (required) instead.

    format

    format: "iife" | "amd" | "umd";
    
    default "umd";

    Defines the format to be used for the Browser build.

    name

    name: string;

    The name to be used to expose your library to the global scope in a IIFE or UMD browser build. If not provided it will default to the camelcased, unscoped "name" field in package.json or the camelcased directory name. If none of those can be obtained, it will throw at build time.

    id

    id: string;

    Optional amd id for AMD or UMD build.

    If not present, AMD define method will use no id.

    extend

    extend: boolean;
    
    default false;

    Whether or not to extend the globally exposed name on a IIFE or UMD build.

    globals

    globals: { [name: string]: string } | string[];
    
    default {};

    Object or array to map names to globals in Browser build.

    min

    min: boolean | SelectiveOption;
    
    default false;

    Defines which files should be used to build an additional minified version, if true will affect all modules. The minified file will be renamed from *.ext to *.min.ext. This option will override the default behavior of the --dev, -d cli option , which means only the minified version will be actually minified, the normal version will NOT be minified even if you don't set the --dev, -d cli option.

    This option supports object based and string based selective format. See Selective Options for more information.

    equals

    equals: boolean;
    
    default false;

    Transforms type export for CommonJS module using export = ... instead of export default ....

    ⚠️ Note that this option should only be used when your library has a default export and no named exports, otherwise it may cause the type declarations to become invalid.

    cache

    cache: string;
    
    default "node_modules/.cache/bundlib";

    Defines the directory to be used for cache, relative to the project root.

    project

    project: string | SelectiveOption;
    
    default "tsconfig.json"

    Defines the location of typescript tsconfig.json file, relative to the project root.

    This option supports object based selective format. See Selective Options for more information.

    skip

    min: boolean | SelectiveOption;
    
    default false;

    Defined which build Bundlib should skip.

    This option supports object based and string based selective format. See Selective Options for more information.

    Selective Options

    Some options support a selective format to allow for a more flexible configuration. See SelectiveOption type for more information.

    Note that some options support different selective formats. Boolean type options support string based format and object based format while others support only object based format.

    See input, sourcemap, esModule, interop, min and project options.

    Object based selective format

    object based format works by preserving the default value and overriding it with the provided configuration.

    example

    // assuming default = false...
    
    {
      main: true
    }
    
    // ... will resolve to
    
    /*
    {
      main: true,
      ...others: false
    }
    */
    The special default property

    You can override the default value as well using the "default" object key.

    example

    // assuming default = false
    
    {
      default: true,
      bin: false
    }
    
    // ... will resolve to
    
    /*
    {
      bin: false,
      ...others: true
    }
    */
    The special api property

    The "api" object key represents main, module and browser.

    example

    // assuming default = false...
    
    {
      api: true
    }
    
    // ... will resolve to
    
    /*
    {
      main: true,
      module: true,
      browser: true,
      ...others: false
    }
    */

    String based selective format

    string based format works in a different way, it does not preserve the default value, included build types will be set to true and the others will be set to false. It can be a string or an string array.

    As string

    example

    'module'
    
    // ... will resolve to
    
    /*
    {
      module: true,
      ...others: false
    }
    */
    As array of strings

    example

    ['main', 'module']
    
    // ... will resolve to
    
    /*
    {
      main: true,
      module: true,
      ...others: false
    }
    */
    The special api build type

    example

    'api'
    
    // ... will resolve to
    
    /*
    {
      main: true,
      module: true,
      browser: true,
      ...others: false
    }
    */

    Using the CLI tool

    bundlib [options]

    CLI Options

    Combine options according to your needs. Run bundlib --help or bundlib -h for a detailed help.

    --dev, -d

    Create development, not minified builds. Builds affected by the min option will ignore this option.

    --watch, -w

    Run Bundlib in watch mode.

    --silent, -s

    Prevent messages from showing in the console.

    --version, -v

    Show Bundlib version.

    --help, -h

    Show detailed help about the CLI tool.

    Using Bundlib programmatically

    example

    // rollup.config.js
    
    import { configsFromPkg } from "bundlib";
    
    const dev = !process.env.production;
    
    export default configsFromPkg(
      process.cwd(),
      { dev },
    );

    analyzePkg

    function analyzePkg(
      cwd: string,
      pkg: PkgJson = read(cwd + "/package.json"),
    ): Promise<PkgAnalyzed>;

    Analyzes package.json and returns a Promise that resolves to useful normalized information, see PkgAnalyzed. If pkg not provided it will be read from the current working directory cwd.

    configsFromPkg

    function configsFromPkg(
      cwd: string,
      options: { dev? boolean, watch?: boolean } | null | false,
      pkg: PkgJson = read(cwd + "/package.json"),
    ): Promise<RollupOptions[]>;

    Returns a Promise that resolves to an array of Rollup configs based on the content of package.json. If pkg not provided it will be read from the current working directory cwd.

    Types

    PkgAnalyzed

    interface PkgAnalyzed {
      cwd: string;
      pkg: PkgJson;
      main: ModuleBuildOptions | null;
      module: ModuleBuildOptions | null;
      browser: BrowserBuildOptions | null;
      bin: ModuleBuildOptions | null;
      types: TypesBuildOptions | null;
      chunks: Record<string, string> | null;
      dependencies: {
        runtime: { [name: string]: string } | null;
        dev: { [name: string]: string } | null;
        peer: { [name: string]: string } | null;
      };
      cache: string | null;
    }

    see also: ModuleBuildOptions, BrowserBuildOptions and TypesBuildOptions.

    ModuleBuildOptions

    interface ModuleBuildOptions {
      input: string | null;
      output: string;
      sourcemap: boolean | 'inline' | 'hidden';
      esModule: boolean;
      interop: boolean;
      min: boolean;
      project: string | null;
    }

    BrowserBuildOptions

    interface BrowserBuildOptions extends ModuleBuildOptions {
      format: "iife" | "amd" | "umd";
      name: string | null;
      id: string | null;
      globals: Record<string, string> | null;
      extend: boolean;
    }

    TypesBuildOptions

    interface TypesBuildOptions {
      output: string;
      equals: boolean;
    }

    SelectiveOption

    interface ObjectBasedSelectiveOption<T> {
      default: T;
      [K: BuildType]: T;
    }
    
    type StringBasedSelectiveOption = BuildType | BuildType[];
    
    type BuildType = 'main' | 'module' | 'browser' | 'bin' | 'api' | ...others;

    Features

    • Uses "main" field in your package.json to build a CommonJS Module.
    • Uses "module" field in your package.json (or "jsnext:main" field) to build an ES Module.
    • Uses "browser" field in your package.json to build a Browser module. It only supports "browser" field as string, object format not supported.
    • Uses "bin" field in your package.json to build a Binary module. It only supports "bin" field as string, object format not supported.
    • Uses "types" field in your package.json (or "typings" field) as path for types declarations.
    • Uses "dependencies" and "peerDependencies" to set external modules for CommonJS Module, ES Module and Binary builds. Dependencies will be bundled by default in Browser builds, unless otherwise specified using the global option.
    • Skip any build based on options.
    • Uses rollup-plugin-typescript2 if typescript installed as runtime or dev dependency.
    • Uses @rollup/plugin-babel if @babel/core installed as runtime or dev dependency, otherwise it uses @rollup/plugin-buble.
    • Uses rollup-plugin-strip-shebang and rollup-plugin-add-shebang to ensure a shebang on binary build.
    • Uses @rollup/plugin-json to import JSON files.
    • Uses@rollup/plugin-eslint if eslint installed as runtime or dev dependency.
    • Uses rollup-plugin-terser to minify production build.
    • Uses chokidar for file watch if installed.

    Future Features

    • Honor "type" field in package.json
    • Honor "exports" field in package.json
    • Support package.json "bin" field as an object for multiple cli commands

    Known issues

    • Type declarations for chunks created using the chunks options may not work properly.

    License

    MIT © 2019 Manuel Fernández

    Install

    npm i bundlib

    DownloadsWeekly Downloads

    814

    Version

    0.18.4

    License

    MIT

    Unpacked Size

    354 kB

    Total Files

    108

    Last publish

    Collaborators

    • avatar