Substance Bundler

Common errors

• TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".js" for .../node_modules/substance-bundler/index.js

  cause 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')

  cause 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'

  cause 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

  cause 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.

Warnings

• 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.
• gotcha When 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.
• gotcha When 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.
• gotcha Inside 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.

Install

• npm install substance-bundler npm
• yarn add substance-bundler yarn
• pnpm add substance-bundler pnpm

Imports

• b
  wrong:

  import b from 'substance-bundler'

  correct:

  const b = require('substance-bundler')

  The main bundler export is a CommonJS module. ESM `import` syntax will cause runtime errors.
• postcss
  wrong:

  import { postcss } from 'substance-bundler/extensions/postcss'

  correct:

  const postcss = require('substance-bundler/extensions/postcss')

  Extensions are also CommonJS modules. Use `require()` to import them correctly.
• rollup
  wrong:

  import rollup from 'substance-bundler/extensions/rollup'

  correct:

  const rollup = require('substance-bundler/extensions/rollup')

  Extensions are also CommonJS modules. Use `require()` to import them correctly.

Quickstart

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`