Registry / devops / substance-bundler

substance-bundler

JSON →
library0.27.4jsnpmunverified

Substance Bundler is a custom JavaScript bundling and build orchestration library, currently at version `0.27.4`. It offers a high-level, shell-script-like approach to defining build processes, distinguishing itself from traditional task runners like Gulp or Grunt by emphasizing simplicity and direct action execution. The library internally leverages `chokidar` for robust file watching, ensuring all defined operations automatically react to source file changes. While not a bundler itself, it seamlessly integrates with popular tools such as Webpack, Rollup, and PostCSS via dedicated extensions, acting as an orchestrator for these underlying technologies. This allows developers to define complex build pipelines, including copying files, removing directories, and executing custom scripts, all within a unified task-based system with inter-task dependencies. Its primary differentiator lies in its low-ceremony API for defining build steps and its integrated watch mode across all tasks, offering a streamlined development experience for projects that require custom but maintainable build logic.

npm install substance-bundler
INSTALL
IMPORT
SIG · SUBSTANCE-BUNDLER
S
substance-bundler
devopsjavascriptv0.27.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

b
const b = require('substance-bundler')
import b from 'substance-bundler'
The main bundler export is a CommonJS module. ESM `import` syntax will cause runtime errors.
postcss
const postcss = require('substance-bundler/extensions/postcss')
import { postcss } from 'substance-bundler/extensions/postcss'
Extensions are also CommonJS modules. Use `require()` to import them correctly.
rollup
const rollup = require('substance-bundler/extensions/rollup')
import rollup from 'substance-bundler/extensions/rollup'
Extensions are also CommonJS modules. Use `require()` to import them correctly.

This `make.js` script demonstrates defining and orchestrating multiple build tasks, including cleaning, CSS compilation via PostCSS, JavaScript bundling with Rollup, and file copying, all managed by `substance-bundler`. It showcases task dependencies and a basic command-line runner for build operations.

const b = require('substance-bundler'); const postcss = require('substance-bundler/extensions/postcss'); const rollup = require('substance-bundler/extensions/rollup'); // Define a task to clean the build output directory b.task('clean', () => { b.rm('dist'); console.log('Removed dist directory.'); }); // Define a task to compile CSS using PostCSS extension b.task('css', () => { console.log('Bundling CSS...'); postcss(b, { from: 'styles/index.css', // Assumes 'styles/index.css' exists to: 'dist/app.css' }); }); // Define a task to bundle JavaScript using Rollup extension // Requires a rollup.config.js and an entry point like index.js b.task('js', () => { console.log('Bundling JavaScript with Rollup...'); // For a runnable example, ensure rollup.config.js and index.js exist const rollupConfig = require('./rollup.config.js'); rollup(b, rollupConfig); }); // Define a task to copy static assets b.task('copy-assets', () => { console.log('Copying assets...'); b.copy('./assets', 'dist/assets/'); // Assumes an 'assets' directory exists }); // Define the default task which runs other tasks sequentially b.task('default', ['clean', 'css', 'js', 'copy-assets'], () => { console.log('All default tasks completed!'); }); // Basic CLI runner (for demonstration, not part of bundler API itself) const tasksToRun = process.argv.slice(2).filter(arg => !arg.startsWith('-')); const watchMode = process.argv.includes('-w'); if (watchMode) { console.log('Running in watch mode...'); b.run(tasksToRun.length > 0 ? tasksToRun : ['default'], { watch: true }); } else { b.run(tasksToRun.length > 0 ? tasksToRun : ['default']); } // To run this script: // 1. Save as `make.js`. // 2. Create dummy `dist`, `styles`, `assets` directories. // 3. Create dummy `styles/index.css`, `index.js`, `rollup.config.js`. // 4. `npm install --save-dev rollup postcss @rollup/plugin-node-resolve` // 5. Execute: `node make.js` or `node make.js -w`
Debug
Known issues
breaking`substance-bundler` is published as a CommonJS module. Attempting to import it using ESM `import` syntax will result in runtime errors (e.g., `TypeError: require is not a function`) in Node.js environments configured for ESM.
fix
Always use `const b = require('substance-bundler')` and `const extension = require('substance-bundler/extensions/...')` in your build scripts. Ensure your script is treated as a CommonJS module.
affects: >=0.1.0
gotchaWhen utilizing bundler extensions such as `rollup`, `webpack`, or `postcss`, their respective npm packages must be installed as peer/development dependencies in your project. `substance-bundler` itself does not bundle these external tools.
fix
Ensure you `npm install --save-dev <package-name>` (e.g., `rollup`, `webpack`, `postcss`) for any extensions you use in your build tasks.
affects: >=0.1.0
gotchaWhen using `b.copy` with glob patterns, especially when copying files to a new directory structure or renaming them, the `options.root` parameter is crucial. Failing to specify `root` can lead to incorrect destination paths, files being placed in unintended locations, or the glob pattern failing to match as expected.
fix
For `b.copy` operations involving glob patterns, explicitly define `options.root` to specify the base directory from which source files are resolved.
affects: >=0.1.0
gotchaInside a `b.custom` task's `execute` function, direct usage of Node.js `fs` module operations (e.g., `fs.writeFileSync`) is generally discouraged. Instead, use the `api` object provided as the second argument (e.g., `api.writeFileSync`), which integrates with `substance-bundler`'s file watching and change propagation mechanisms.
fix
Replace `fs.writeFileSync(path, data)` with `api.writeFileSync(path, data)` and similar `fs` calls with `api` methods within `b.custom` task `execute` functions to ensure proper bundler integration.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".js" for .../node_modules/substance-bundler/index.js
Attempting to use ESM `import` syntax (e.g., `import b from 'substance-bundler'`) to load `substance-bundler` in an environment configured for ESM (e.g., `"type": "module"` in `package.json`).
fix
Change your import statement to `const b = require('substance-bundler')`. If your entire project is ESM, you might need to wrap your `substance-bundler` script in a CommonJS context or adjust your module resolution.
Error: Cannot find module 'rollup' (or 'webpack', 'postcss')
You are using a `substance-bundler` extension (e.g., `substance-bundler/extensions/rollup`) but have not installed the corresponding external package (`rollup`) in your project's `node_modules`.
fix
Install the missing package as a development dependency: `npm install --save-dev rollup` (or `webpack`, `postcss`).
[bundler] Task 'clean' failed: Error: EEXIST: file already exists, mkdir 'dist'
A task (e.g., `b.custom` or `b.copy`) attempts to create a directory (`dist`) that already exists, and the operation is not configured to handle existing directories idempotently. This often happens if a 'clean' task (which removes `dist`) is not run or fails before other tasks that create `dist`.
fix
Ensure your 'clean' task (e.g., `b.rm('dist')`) is configured as a dependency and runs before tasks that create build output directories, or explicitly add logic to skip directory creation if it already exists.
(node:12345) UnhandledPromiseRejectionWarning: Error: No input files found for pattern: styles/**/*.css
A `b.copy` or `b.custom` task with a glob pattern (`styles/**/*.css`) cannot find any files matching the specified pattern, likely due to a typo in the path, incorrect relative pathing, or the files not existing at the given location.
fix
Verify that the glob pattern in your `src` path is correct, that the specified directory exists, and that the intended source files are present at that location relative to your `make.js` script.
Upgrade
Version history
0.27.4latest on npm
Audit
Dependencies
webpackoptionalRequired if using `substance-bundler/extensions/webpack` to integrate Webpack into build tasks.
rollupoptionalRequired if using `substance-bundler/extensions/rollup` to integrate Rollup into build tasks.
postcssoptionalRequired if using `substance-bundler/extensions/postcss` to integrate PostCSS into build tasks.
Agent activity
6 hits · last 30 days
node
6
Resources