Substance Bundler

This is our custom bundling library, which is similar to gulp or grunt, but from regarding usage it is more like a shell script or make file. All operations support file watching (using chokidar). All actions can be organised in tasks, and tasks can depend on each other. We use it as a high-level bundling tool, in combination with webpack, rollup, and postcss.

API

const b = require('substance-bundler')

`b.copy(src, dest, options)`

Copy a file or directory to a destination folder. src allows for glob patterns. The destination directory is created if it does not exist.

Copy a single file into dist folder:

copy('./foo.js', 'dist/')

Copy a single file with renaming

copy('./foo.js', 'dist/bar.js')

Copy a whole directory into dist folder

copy('./assets', 'dist/')

Copy a whole directory into dist folder with renaming

copy('./node_modules/substance/dist', 'dist/lib/substance')

Copy using a glob pattern

copy('./node_modules/substance/dist/**/*.css', 'dist/styles/', { root: './node_modules/substance/dist/'})

`b.rm(path)`

Remove a file or directory, essentially like rm -rf.

b.rm('tmp')

`b.custom(descr, { src, [dest], execute })`

Perform a custom action.

src can be a single path or a glob pattern, or an array of such. Source files are watched for changes.
dest is optional and enables the bundler to propagate changes, e.g. removing generated files.
execute(files, api) is called initially and whenever the source files have changed

Example:

b.custom('Create version file', {
  src: 'package.json',
  dest: 'VERSION',
  execute (file, api) {
    let pkg = require('./package.json')
    api.writeFileSync('VERSION', pkg.version)
  }
})

The first argument, files, of the execute() handler is particularly useful, if glob patterns are used. The second argument, api, provides the following methods:

watch(path): adds a watcher for a given file path
isAbsolute(path): helper to check if a path is absolute or relative
isDirectory(path): helper to check if a path is a directory
copySync(src, dest): copy a file or directory (see b.cp())
mkdirSync(dir): create a directory
rmSync(path): deletes recursively like rm -rf
writeFileSync(path, data): write data to a file (destination dir is created automatically)

`b.task(name, [dependencies], execute)`

Example:

make.js:

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

b.task('clean', () => {
  b.rm('dist')
})

b.task('css', () => {
  postcss({
    from: 'styles/index.css',
    to: 'dist/app.css'
  })
})

b.task('lib', () => {
  rollup(b, require('./rollup.config'))
})

b.task('default', ['clean', 'css', 'lib'])

> node make           // runs 'default' task
> node make css lib   // runs tasks 'css' and 'lib'

Watcher

> node make -w

Runs the build once and watches for changes.

Extensions

Extensions make use of custom commands.

rollup

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

rollup(b, require('./rollup.config'))

See rollup documentation

webpack

const b = require('substance-bundler')
const webpack = require('substance-bundler/extensions/webpack')

webpack(b, require('./webpack.config'))

See webpack documentation

postcss

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

postcss(b, {
  from: 'substance.css',
  to: 'dist/substance.css'
})

See postcss documentation

Bundler comes with a bundled postcss and predefined set of plugins (@import and reporter). Both can be overridden:

postcss(b, {
  from: 'substance.css',
  to: 'dist/substance.css',
  postcss,
  plugins: [...]
})

exec

Execute a program using node's child_process module, cp.spawn().

const b = require('substance-bundler')
const exec = require('substance-bundler/extensions/exec')

exec(b, command, args, [options])

options

silent: no output to stdout or stderr
verbose: show output to stdout as well to stderr (default is only to stderr)
options for cp.spawn(): see child_process documentation

fork

Same as exec but using cp.fork()

substance / bundler