FCL-Bundle Overview

FCL-Bundle is a module bundler used internally by FCL which aims to be low configuration and consistent across the monorepo. FCL-Bundle uses rollup and generates cjs, esm, and umd formats of the bundled modules.

CLI Usage

Usage: fcl-bundle [options]

Options:
-V, --version output the version number
-w, --watch Run the build in watch mode
-h, --help display help for command

Configuration

All of the configuration for FCL-Bundle currently takes place within the package.json of the modules which you wish to bundle. The following configuration options are available:

| Key | Required | Value Type | Description | |----------|----------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | source | Yes | string | Specify a source file entry point or an dictionary of Output Configuration objects keyed by respective source files (for multiple builds) - see Source Configuration for more details | | main | No | string | Specify cjs bundle output path if not manually specified by Output Configuration (as well as cjs entry point if not overridden by package.exports) | | module | No | string | Specify esm bundle output path if not manually specified by Output Configuration (as well as esm entry point if not overriden by package.exports) | | unpkg | No | string | Specify umd bundle output path if not manually specified by Output Configuration (as well as umd entry point if not overriden by package.exports) |

Note: If output paths end in ".min.js", the resulting bundle will be minified

Output Configuration

An Output Configuration object exists with the following properties: | Key | Required | Value Type | Description | |----------|----------|------------|----------------------------------------------------------------------------------------------------------------------------| | cjs | No | string | Path of the cjs output bundle | | esm | No | string | Path of the esm output bundle | | umd | No | string | Path of the umd output bundle | | banner | No | string | Either a string representing a banner to be prepended to all output bundles for this build or a Banner Configuration object |

An empty Output Configuration will fallback to the default outputs if none are provided. However, if at least one output format is provided, the missing outputs will be excluded from the final build.

In practice, these Output Configuration objects will be consumed as shown in the Source Configuration below.

Note: If output paths end in ".min.js", the resulting bundle will be minified

Source Configuration

A source configuration can be provided in one of three ways:

1. A string identifying the path to the entry source file. Build outputs will be inferred from either the root level main, module, and unpkg fields or from the default outputs if none are provided.

   {
     ...
     "source": "./src/index.js",
   }

2. An array of entry source files. Build outputs will be inferred from the default outputs.

   {
     ...
     "source": [
       "./src/indexA.js",
       "./src/indexB.js"
     ]
   }

3. A dictionary of Output Configuration objects keyed by respective source files.

   {
     ...
     "source": {
       "./src/indexA.js": {
         "cjs": "./dist/indexA.js"
       },
       "./src/indexB.js": {
         "cjs": "./dist/indexB.js",
         "esm": "./dist/indexB.module.js"
       },
       "./src/indexC.js": {
         "cjs": "./dist/indexC.js",
         "esm": "./dist/indexC.module.js",
         "umd": "./dist/indexC.umd.js"
       }
     }
   }

Default Outputs

Note: if no output bundles (cjs,esm,umd) are specifified in either the root of package.json (main, module, unpkg) or an Output Configuration object, the bundler will produce the following defaults:

• cjs -> dist/${basename(entry)}.js
• esm -> dist/${basename(entry)}.module.js
• umd -> dist/${basename(entry)}.umd.js

Banner Configuration

| Key | Required | Value Type | Description | |----------|----------|------------|----------------------------------------------------------------------------------------------------------------| | banner | Yes | string | Text to be displayed in banner | | raw | No | boolean | If false, wraps the banner in JS comment, if true no extra formatting is applied to banner (default false) |

Features

• Replace PACKAGE_CURRENT_VERSION in bundled code with the current version of the package being bundled from package.json
• Bundles dependencies with UMD builds for use in browser
• Transpiles output bundles using @babel/preset-env and babel rollup plugin
• PostCSS support for CSS bundling, must include a postcss.config.js in the root of the package
• Images are bundled with the @rollup/plugin-image plugin as base64 strings
• Minification of bundles with terser if output paths end in ".min.js"
• TypeScript support if entry point is a .ts file