@bundles/core v0.9.4

Bundles Core

Bundles is a file bundler, similar to WebPack, RollupJS, Parcel, PostCSS, etc., except that while other bundlers are designed to compile to a specific type of output (like JS, CSS, etc.), Bundles can compile from anything, to anything! Bundles has no assumptions and places no limitations on the type of input it takes and what it outputs to. It simply takes input, runs it through a series of "bundlers" (i.e., simple JS plugins), and processes your data however you tell it to. Use Bundles to compile literally anything your heart desires (and can dream up)!

Environment support

Terminology

To be clear, the usage of the following terms are defined as follows:

• Bundles (capitalized): The core package / tool for Bundles.
• bundles: Results compiled by Bundles. More specifically this refers to the results.bundles returned by Bundles. This may also refer to config.bundles, which eventually turns into results.bundles.
• bundle (noun): A single or specific result compiled by Bundles. An item in the results.bundles Array (i.e., results.bundles[n]).
• bundle (verb): The process of running input through a series of bundlers to achieve a desired output.
• bundler: A simple JavaScript function which Bundles uses to process / compile input however you like. Without bundlers, Bundles will simply output source input. With bundlers, Bundles can output just about anything you want.
• config: Refers to user configuration.
  • global config: Refers to the global config Object.
  • bundles config: Refers to config.bundles.
  • bundle config: Refers to a specific bundle, i.e., config.bundles[n].

Install

npm install @bundles/core -D

Usage

Bundles can be run in Node or the command line:

Node:

const bundles = require('@bundles/core');
bundles(config, options);

CLI:

bundles <source files> [options]

Note: All runtime options get merged down to config.options. options only exists separate from config.options to allow user to pass runtime options (i.e., the watch flag), which override config.options.

Configuration

Bundles' API is designed to be as minimal as possible so as to be easy to use, while also retaining a reasonable amount of flexibility. It is intended that most configuration can and should come from bundlers.

• bundles (required) {Object[]} Bundle configuration Objects which determine how each bundle is to be processed. Each bundle has the following properties:

  • input (required) {String|Glob} Input files to process.
  • bundlers (required) {String[]|Function[]|Object[]} Each bundler processes or compiles the content and/or data from input in a specified way. See bundler Objects.
  • id {String} ID / identifier for this bundle. If this doesn't exist, Bundles will use its index position in bundles.

• on {Object} Callback functions which hook into the Bundles workflow. Potential hooks include:

  • afterChange( bundle, { filepath, config } ) {Function} Runs after a source file changes, but only if the file is being watched.

• options {Object} Configuration options. IMPORTANT: Any options passed to Bundles -- either from the command line or in Node -- get merged here.

  • bundles {String|Array} Should be a comma-separated list or an Array of bundle IDs. This option tells Bundles which bundles to run. It allows you to only run a selected number of bundles rather than all that are configured.
  • watch {Boolean|String} Set true to watch all bundles. Pass a comma-separated String to only watch the bundle IDs listed.
  • loglevel {String} Determines how to log information. Can be 'trace', 'debug', 'info', 'warn', 'error', or 'silent'.
  • glob {Object} Options passed directly to globby.
  • frontMatter {Object} Options passed directly to gray-matter.
  • chokidar {Object} Options passed directly to chokidar.

The Bundle Object

It is important to understand the bundle Object in order to grasp how Bundles, and bundler plugins, work. Each bundle contains the following properties:

• id {String} The bundle ID. Defaults to its index position.
• input {String[]} Array of input file paths (Strings) returned by globby.
• output {Object[]} Each Object is a file Object with the following properties:
  • source {Object} The source file is read in and this source Object created by gray-matter. These properties should not be modified. source contains the following properties (along with all other properties returned by gray-matter):
    • path {String} Source file path.
    • content {String} Source content (should not be modified).
    • data {String} Source front matter data (should not be modified).
  • content {String} Output content (can be modified).
  • data {String} Output front matter data (can be modified).
• bundlers {Object[]} A bundler is a plugin that processes/compiles content/data. See bundler Objects.
• watch {Boolean} Whether this bundle is configured to be watched.
• on {Object} Callback functions to hook into core functionality.

Bundler Objects

A bundler is a JavaScript plugin that processes content and/or data from config.input. A bundler can be configured any of the following ways:

• A Function: (bundle = {}, bundler = {}) => { // Do something cool. }.
• A Node module: 'my-cool-bundler' or './path/to/bundler'
• An Object, where the run property is a Node module or a Function. This allows you to attach bundler specific configuration.

During runtime, each bundler is normalized to an Object with the following properties:

• success {Boolean} Whether the bundler ran successfully.
• error {Error} Error Object if an error occurs running the bundler.
• run {Function} The bundler Function which processes the bundle. If it is a node module it is the default export for that module, which must be a function.
• _meta {Object} Private metadata about the bundler.

Other properties are typically available to allow users to configure each bundler. Make sure to read documentation for each bundler for how to configure them.

The Result Object

Upon completion (i.e., after running all bundlers), Bundles returns a result Object similar to the original config Object. The result Object has the following useful properties:

• success {Boolean} Whether all bundles compiled successfully.
• bundles {Object[]} Bundles that ran. Each bundle Object has the following properties:
  • success {Boolean} Whether bundle compiled successfully.
  • output {Object[]} File(s) to output.
  • watch {Boolean} Whether the bundle is being watched.
  • _meta {Object} Metadata used internal.
• bundlesMap {Object} Dictionary of bundles that ran, organized by bundle ID. Provided simply for an alternative way to look up bundle results.
• options {Object} Run time options, merged with configuration options.
• watchers {Object} A dictionary of watchers created by chokidar, organized by bundle ID.
• on {Object} A dictionary of configured callbacks, organized by callback name.
• _meta {Object} Metadata used internally. May change at any time.

Using bundlers

Creating a bundler

It is easy to create your own custom bundler. A bundler is simply a function which returns the bundle. Here are two simple examples:

const fs = require('fs');
module.exports = (bundle = {}, bundler = {}) => {
  bundle.output.forEach((result) => {
    result.content = result.content += '\n';
    return result.content;
  });
  // Must return the bundle Object.
  return bundle;
};

You may also return a Promise which returns the bundle Object:

const fs = require('fs');
module.exports = (bundle = {}, bundler = {}) => {
  // Return a promise...
  return new Promise((resolve) => {
    bundle.output.forEach((result) => {
      result.content = result.content += '\n';
      return result.content;
    });
    // ...which resolves the bundle Object.
    return resolve(bundle);
  });
};

Guidelines for creating a bundler

1. A bundler must return a function which returns the modified bundle Object. The function receives, and allows you to use, the following parameters (see examples above):

   • bundle {Object} The bundle Object.
   • bundler {Object} The bundler configuration. This allows users to provide bundler-specific configuration.

2. Only modify the bundle Object. Other parameters are provided as read-only context, and it is strongly encouraged not to modify these Objects.

3. Internally, the bundler Object only uses a few properties. This allows bundler authors flexibility in how they provide their custom set of configuration properties for their users. However, as a caution, Bundles reserves the right to add more internal properties in the future (any breaking changes, of course, will be semantically versioned), so bundler authors are encouraged to wrap their configuration in a single parent Object such as options (i.e., bundler.options). See bundler Objects for more about bundlers and their properties.