Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Builder
✓ const Builder = require('systemjs-builder');
The primary API is exposed as a CommonJS module. ESM import is generally not supported for the programmatic API.
bundle
✓ builder.bundle('local/module.js', 'outfile.js')
✗ import { bundle } from 'systemjs-builder'
The `bundle` method is accessed via an instance of the Builder class. It's not a named export from the package directly.
buildStatic
✓ builder.buildStatic('myModule.js', 'outfile.js', options);
✗ import { buildStatic } from 'systemjs-builder'
Used for creating self-executing (SFX) bundles. Also accessed via a Builder instance, not a direct export.
Demonstrates how to initialize the Builder, configure it with a base URL and SystemJS config file, and then create a standard bundle, including minification and source maps.
const path = require("path");
const Builder = require('systemjs-builder');
// Install babel-core separately: npm install babel-core
// Ensure you have a 'src/app.js' and a 'system.config.js' in your project for this to run.
// Example system.config.js: System.config({ map: { jquery: './src/jquery.js' } });
// Example src/app.js: import $ from 'jquery'; export var hello = 'es6';
// Example src/jquery.js: define(function() { return 'this is jquery'; });
// Point to your project's base URL and SystemJS config file
const baseURL = path.resolve(__dirname, 'src');
const configFile = path.resolve(__dirname, 'system.config.js');
// Initialize the builder
const builder = new Builder(baseURL, configFile);
console.log(`Building module 'app' from ${baseURL} with config ${configFile}...`);
builder
.bundle('app.js', 'dist/bundle.js', { minify: true, sourceMaps: true })
.then(function() {
console.log('Build complete: dist/bundle.js created.');
})
.catch(function(err) {
console.error('Build error:', err);
});
systemjs-builder --version
Debug
Known issues
breakingSystemJS Builder is officially deprecated as of SystemJS 2.0. Users are encouraged to migrate to Rollup for modern JavaScript module bundling and code splitting. While it supports legacy SystemJS 0.21 builds, it will not receive new features.fixFor new projects or SystemJS 2.0+, use Rollup with appropriate plugins (e.g., @rollup/plugin-systemjs) instead. For existing SystemJS 0.x projects, continue using systemjs-builder 0.16.x if migration is not feasible.
affects: >=0.16.0
gotchaExternal transpilers (e.g., `babel-core`) are not installed as direct dependencies. You must manually install them (`npm install babel-core`) for ES6+ syntax to be correctly transpiled during the build process.fixBefore running a build, ensure all necessary transpiler packages are installed in your project's `node_modules`. For example: `npm install --save-dev babel-core`.
affects: >=0.1.0
breakingWhen building for SystemJS 0.19, you must specifically use `systemjs-builder` version 0.15. Newer 0.16.x versions are incompatible with 0.19.fixIf targeting SystemJS 0.19, downgrade `systemjs-builder` to version 0.15: `npm install systemjs-builder@0.15`.
affects: >=0.16.0
gotchaVersions of `systemjs-builder` prior to 0.16.15 may experience issues with minification due to incompatible `Terser` versions, potentially leading to build failures or incorrect output.fixUpgrade to `systemjs-builder@0.16.15` or later to leverage the fixed `Terser` dependency: `npm install systemjs-builder@0.16.15`.
affects: >=0.16.0 <0.16.15
gotchaSelf-Executing (SFX) bundles in versions 0.16.11 and 0.16.12 experienced regressions related to CommonJS module interop and `Object.defineProperty(module.exports)` assignments. This could lead to incorrect module exports or runtime errors.fixUpgrade to `systemjs-builder@0.16.13` or later to resolve SFX build regressions. Thoroughly test SFX builds after upgrading.
affects: 0.16.11, 0.16.12
Errors
Common errors & fixes
Error: Cannot find module 'babel-core'
A transpiler (like babel-core) required for processing your source code's syntax was not installed.
fixInstall the required transpiler as a development dependency: `npm install --save-dev babel-core` (or the appropriate transpiler for your setup).
Build error
A generic error occurred during the bundling process, often due to misconfigurations, unresolvable modules, or syntax errors.
fixCheck the detailed error message printed to the console (the `err` object in the catch block). Verify your SystemJS configuration, ensure all modules are resolvable, and confirm there are no syntax errors in your source code.
Output bundle is not minified or contains syntax errors after minification.
Issues with the integrated minifier (Terser) or an older version of `systemjs-builder` that had incompatible `Terser` dependencies.
fixEnsure you are using `systemjs-builder@0.16.15` or later. Verify that the `minify: true` option is correctly passed to `builder.bundle()` or `builder.buildStatic()`.
Audit
Dependencies
babel-corerequiredRequired for transpilation of ES6+ syntax during the build process if your source code uses it. It is not an automatic dependency and must be installed separately.