Configurable JSPM Bundler

0.1.11 · active · verified Tue Apr 21

jspm-bundler is a Node.js build tool providing advanced, configurable bundling for applications built with JSPM. It allows developers to define and manage their bundle manifests in an external JavaScript file, `bundles.js`, rather than directly modifying `config.js`. This approach simplifies version control, enables independent updates of bundle configurations, and is especially useful in environments where `config.js` is dynamically generated or managed. The library supports bundling specific module groups, offers robust exclusion capabilities for packages or groups, implements cache busting through generated file checksums, and can produce self-extracting (static) bundles. Currently at version 0.1.11, the package demonstrates a maintenance cadence with recent updates addressing bug fixes, dependency compatibility, and adding new configuration options like `packagePath` and `configFile`. It serves a niche within the JSPM ecosystem by offering more granular control over the bundling process compared to JSPM's built-in bundler.

Common errors

```
Cannot read properties of undefined (reading 'bundle')
```
cause Attempting to use `jspm-bundler` with ESM `import` syntax in a Node.js environment.

fix Use CommonJS `require` syntax: `var Bundler = require('jspm-bundler');`
```
Error: "Invalid destination filename"
```
cause The `dest` or `file` options, or custom filenames specified in `bundles.groupName.items` as object values, are not valid file system paths or names.

fix Verify that all specified file paths and names are valid and accessible for writing. Avoid invalid characters or conflicting directory/file names.
```
Error: "bundle() promise resolving too soon"
```
cause A bug in earlier versions caused the bundling promise to resolve before the operation was complete, leading to race conditions or incorrect assumptions about bundle readiness.

fix Update `jspm-bundler` to version `0.1.7` or newer, which contains a fix for this bug.
```
Error: "unbundle() not returning promise"
```
cause In versions prior to 0.1.2, the `unbundle()` method incorrectly did not return a Promise, making it difficult to chain operations or handle completion asynchronously.

fix Update `jspm-bundler` to version `0.1.2` or newer. If staying on an older version, treat `unbundle()` as synchronous or use callbacks where applicable.

Warnings

breaking The configuration options `bundleDest` and `bundleFile` were renamed to `dest` and `file` respectively.
Fix: Update your configuration to use `dest` and `file` instead of the old names. For example, `dest: 'bundles'` instead of `bundleDest: 'bundles'`.
breaking Gzip compression support was removed from the bundler.
Fix: Remove any `gzip` related configuration options from your bundler setup. If gzip compression is required, it must be handled as a separate post-processing step outside of jspm-bundler.
gotcha Cache busting (`bust: true`) is incompatible with self-extracting bundles (`builder.sfx: true`). Cache busting relies on separate checksums for individual modules, which are not applicable to a single, statically built output file.
Fix: If using self-extracting bundles, set `bust: false`. If cache busting is critical, avoid `sfx: true` and rely on standard JSPM bundles and `bust` functionality.
gotcha The bundler experienced compatibility issues with JSPM v0.16.34, leading to a reversion of updates to that specific JSPM version.
Fix: Exercise caution when using specific JSPM versions with jspm-bundler. If encountering unexpected bundling issues, check the `jspm-bundler` release notes for known JSPM compatibility concerns and consider pinning to a known stable JSPM version.
gotcha The `baseURL` option in the jspm-bundler configuration must precisely match the `baseURL` defined in your SystemJS `config.js`.
Fix: Ensure that `bundler.baseURL` is identical to `System.baseURL` configured for your JSPM project. Mismatches can lead to module resolution errors during bundling.

Install

npm install jspm-bundler npm
yarn add jspm-bundler yarn
pnpm add jspm-bundler pnpm

Imports

Bundler
wrong:
```
import Bundler from 'jspm-bundler';
```
correct:
```
var Bundler = require('jspm-bundler');
```
This package is a CommonJS module and must be imported using `require()` syntax. Direct ESM `import` will not work.

Quickstart

Demonstrates initializing the bundler with a configuration, specifying bundle groups, and executing a bundle operation for a specific group.

var Bundler = require('jspm-bundler');

var bundler = new Bundler({
    baseURL: './',
    configFile: 'config.js',
    packagePath: './',
    dest: 'bundles',
    file: 'bundles.js',
    bust: false,
    builder: {
        sfx: false,
        minify: false,
        mangle: false,
        sourceMaps: true,
        separateCSS: false,
        lowResSourceMaps: true,
        config: {}
    },
    bundles: {
        appGroup: {
            bundle: true,
            combine: false,
            exclude: [],
            items: [
                'angular',
                'jquery',
                'source/app'
            ]
        },
        routesGroup: {
            bundle: true,
            items: {'source/routes': 'dist-routes'}
        }
    }
});

bundler.bundle(['appGroup']).then(function(){
    console.log('Successfully bundled appGroup.');
}).catch(function(err) {
    console.error('Error bundling appGroup:', err);
});

view raw JSON →