Splittable Bundler

Common errors

• Compilation failed

  cause A general error indicating issues during the bundling process, potentially due to incorrect configuration, source code errors, or underlying Closure Compiler failures.
  fix Check the console for any detailed error messages or warnings provided by Splittable or Closure Compiler. Ensure source paths are correct and all dependencies (like Java) are properly set up. Enable `warnings: true` in options for more verbose output.

• java.lang.NoClassDefFoundError: com/google/javascript/jscomp/CommandLineRunner

  cause This error indicates that the Java runtime cannot find the Closure Compiler's main class, typically because the Closure Compiler JAR is missing or not accessible to Splittable. This usually points to an issue with the Java installation or Splittable's internal dependency resolution for Closure Compiler.
  fix Verify your Java installation and ensure it's correctly configured in your system's PATH. If `splittable` was globally installed, try reinstalling it. Check for any environment variables that `splittable` might use to locate the Closure Compiler JAR.

• ReferenceError: Promise is not defined

  cause The `System.import` polyfill used by Splittable's generated bundles requires a global `Promise` object, which is missing in older JavaScript environments (e.g., IE11).
  fix Include a Promise polyfill in your HTML before loading Splittable's `_base.js` bundle. A common choice is PJs or a polyfill from `core-js`.

• Error: Failed to load module 'module/path': 404 Not Found

  cause The `System.import` loader could not find the requested module bundle at the specified path. This often happens if `System.baseURL` is incorrect or the module path itself is misspelled.
  fix Double-check that `System.baseURL` is correctly set to the root directory where your Splittable bundles (including `_base.js`) are deployed. Verify the exact `module/path` string matches an entry module configured during bundling.

Warnings

• breaking Splittable relies on Java for the Google Closure Compiler. If Java is not installed or correctly configured in the system's PATH, Splittable will fail to run.
  Fix: Ensure Java Development Kit (JDK) or Java Runtime Environment (JRE) is installed and its `bin` directory is included in your system's PATH environment variable.
• gotcha When using Babel with Splittable, it is highly recommended to disable ES6 module transpilation (e.g., `modules: false` in `babel-preset-es2015` or similar presets). Splittable performs its own ES6 module compilation at a later stage, and pre-transpiling modules can lead to "very poor" (inefficient or bloated) generated code.
  Fix: Configure your Babel presets to explicitly set `modules: false` for ES6 module transformations. Example: `['es2015', { loose: true, modules: false }]`.
• gotcha The `System.import` polyfill provided by Splittable's `_base.js` bundle requires a global `Promise` implementation. For older browsers that lack native Promise support, you must supply your own Promise polyfill (e.g., PJS or core-js).
  Fix: Include a Promise polyfill script (e.g., `<script src="path/to/PJs.min.js"></script>`) before loading your Splittable bundles in HTML for environments without native Promises.
• gotcha When loading bundles with `System.import`, the `System.baseURL` global variable must be explicitly set to the deployed directory of your Splittable bundles. Failing to do so will prevent the loader from finding and importing modules.
  Fix: Before any `System.import` calls, define `System.baseURL = '/path/to/your/bundles/';` where `/path/to/your/bundles/` is the web-accessible directory containing `_base.js` and other generated bundles.
• gotcha Splittable supports CommonJS modules but with 'some caveats'. Specifically, cyclic dependencies are not supported and some Node.js modules may not be compatible due to environment differences. Also, `require("module-name")` must be used for NPM modules, even inside ES6 modules.
  Fix: Avoid cyclic dependencies in your CommonJS modules. Test NPM modules thoroughly for compatibility. Use `require()` for NPM module imports, regardless of the surrounding module format.

Install

• npm install splittable npm
• yarn add splittable yarn
• pnpm add splittable pnpm

Imports

• splittable
  wrong:

  import splittable from 'splittable';

  correct:

  const splittable = require('splittable');

  Splittable is a CommonJS module. Direct ES module `import` syntax is not supported for the bundler itself. The `System.import` described in the README is for loading *output bundles*, not the `splittable` library.

Quickstart

This quickstart demonstrates how to programmatically use Splittable to bundle two entry modules, `a.js` and `b.js`, into separate output bundles, including a shared `_base.js` bundle. It creates a temporary project structure, executes the bundler, and logs success or failure with warnings.

const splittable = require('splittable');
const path = require('path');
const fs = require('fs');

// Create a dummy project structure for the example
const tempDir = path.join(__dirname, 'temp_splittable_project');
const libDir = path.join(tempDir, 'lib');
const outDir = path.join(tempDir, 'out');

fs.mkdirSync(libDir, { recursive: true });
fs.mkdirSync(outDir, { recursive: true });

fs.writeFileSync(path.join(libDir, 'a.js'), 'export function sayHello() { console.log("Hello from A!"); }');
fs.writeFileSync(path.join(libDir, 'b.js'), 'import { sayHello } from "./a"; sayHello(); console.log("From B");');

console.log('Starting Splittable bundling...');
splittable({
  modules: [path.join(libDir, 'a.js'), path.join(libDir, 'b.js')],
  writeTo: outDir,
  warnings: true // Enable Closure Compiler warnings
})
.then(function(info) {
  if (info.warnings) {
    console.warn('Compilation successful with warnings:', info.warnings);
  } else {
    console.log('Compilation successful.');
  }
  console.log('Bundles written to:', outDir);
})
.catch(function(reason) {
  console.error('Compilation failed:', reason);
})
.finally(() => {
  // Clean up dummy project (optional)
  // fs.rmSync(tempDir, { recursive: true, force: true });
  // console.log('Cleaned up temporary project directory.');
});