dcompose

Asset composer

npm install dcompose
1 downloads in the last week
101 downloads in the last month

dcompose

CommonJS bundler for javascript and CSS.

What does it mean? It means you can write code which requires other code and... stylesheets:

var styles = require('./button.css');
var dependency = require('./button.js');

...

Installation

% npm install -g dcompose

Usage

There is a command line utility dcompose:

% dcompose --help
Usage: dcompose [options] entry

Options:
  -h, --help          Show this message and exit
  -v, --version       Print dcompose version
  -d, --debug         Emit source maps
  -w, --watch         Watch for changes and rebuild (--output should be passed)
  -o, --output        Set output directory
  --js                Bundle JS dependencies only
  --css               Bundle CSS dependencies only
  -t, --transform     Apply transform
  --css-transform     Apply CSS transform
  --global-transform  Apply global transform
  --extension         File extensions to treat as modules [default: .js]

Usage from Node.js is also possible:

var dcompose = require('dcompose');

dcompose('./entry.js', {debug: true})
  .bundleJS(function(err, bundle) {
    console.log(bundle);
  });

Usage examples

Produce a bundle:

% dcompose ./app.js > ./app.bundle.js

You can bundle CSS dependencies separately:

% dcompose --css ./app.js > ./app.bundle.css

You can bundle JS dependencies separately:

% dcompose --js ./app.js > ./app.bundle.js

Produce a bundle with source map information (debug mode):

% dcompose --debug ./app.js > ./app.bundle.js

Produce a bundle and start watching on changes:

% dcompose --watch --output ./app.bundle.js ./app.js

Handling CSS dependencies

Regarding javascript dependencies this works exactly like browserify. Regarding stylesheet dependencies there are two strategies supported by dcompose:

By default CSS dependencies will be wrapped into CommonJS module which will append stylesheet to a DOM when executed first time. This is not superefficient but will provide a quick start for prototyping.

Another approach is to bundle CSS dependencies separately, for that there's --css option which will bundle only CSS dependencies from a dependency graph:

% dcompose --css ./app.js > ./app.bundle.css

After that you can include app.bundle.css like you normally would in <link> element.

API

dcompose(entries, opts)

Create a new composer object with the following arguments:

  • enrties is a single module specification or an array or those
  • opts is an options object
Module specification

You can specify a module name which will be resolved using Node modules resolving mechanism, so "jquery", "./React" or "./lib/router.js" would be fine.

Alternative you can specify an object of the following shape

{
  id: string,
  expose: boolean | string,
  entry: boolean,
  source: string | buffer,
  deps: {
    <local module id>: <absolute path to module source>,
    ...
  }
}

All fields except id are optional:

  • expose — if true when module will be exposed using its id, if it's a string then it will be used as a public module identifier instead of its id

  • entry — if module should be executed when bundle is loaded (by default true for all modules in entries argument)

  • source — module source, if it's specified then module dependencies should be also specified

  • deps — an object which defined module dependencies in the format of mapping from local module ids (those use in require(...) calls to absolute filenames pointing to the deps' sources

Options
  • transform — a single transform or an array of transforms, transform is a module id which exports transform function or transform function itself. Browserify and dgraph transform are supported.

  • cssTransform — a single CSS transform or an array of CSS transforms, transform is a module id which exports transform function or transform function itself. xcss transforms are supported.

  • extensions — an array of extensions to use then resolving a require with no extension provided, by default only .js files a re considered.

  • debug — emit source maps (works both from CSS and JS)

  • watch — start watching for source changes and emit update event

Events

Composer object is an EventEmitter and emits the following events during lifecycle:

  • update — when an update to code in dependency graph occurs.

dcompose.bundle([cb])

Produce bundle of JS and CSS dependencies.

dcompose.bundleJS([cb])

Produce bundle of JS dependencies.

dcompose.bundleCSS([cb])

Produce bundle of CSS dependencies.

npm loves you