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()`