parcelify

Parcelify

Output css or other bundles based on the browserify dependency graph.

• Use npm packages for reusable interface components.
• Easily include transforms for scss, less, etc. on a per-package basis.
• Rebuild bundles automatically with watch mode.

Many thanks to James Halliday for his help and guidance in bringing this project into reality.

How dat work?

├── node_modules
│   └── my-module
│       ├── index.js
│       ├── myModule.css
│       └── package.json
└── main.js

In my-module's package.json, the module's style assets just need to be enumerated (glob notation):

{
  "name" : "my-module",
  "version": "1.5.0",
  "style" : "*.css"
}

In main.js, everything looks the same:

myModule = require( 'my-module' );

console.log( 'hello world' );

After parcelify is run from the command line,

$ parcelify main.js -c bundle.css

Now bundle.css has all the css in the modules on which main.js depends (in this case myModule.css).

Installation

$ npm install -g parcelify

Command line options

--cssBundle, -c   Path of a destination css bundle.

--tmplBundle, -t  Path of optional template bundle (see below discussion on client side templates).

--watch, -w       Watch mode - automatically rebuild bundles as appropriate for changes.

--jsBundle, -j    Path of the JavaScript bundle (i.e. browserify's output).

--debug, -d       Enable source maps that allow you to debug your js files separately.
                  (Passed through to browserify.)

--help, -h        Show this message

package.json

Two keys are special cased in package.json files.

• The style key is a glob or array of globs that enumerates the style assets of the module.
• The tranforms key is an array of names or file paths of transform modules to be applied to assets.

{
  "name": "my-module",
  "description": "Example package.json for hypothetical myModule.",
  "version": "1.5.0",
  "style" : "*.scss",
  "transforms" : [ "sass-css-stream" ],
  "devDependencies" : {
    "sass-css-stream": "0.0.1"
  }
}

API

p = parcelify( mainPath, [options] )

mainPath is the path of the JavaScript entry point file. options are as follows:

{
    bundles : {
      script : 'bundle.js',        // path of javascript bundle (not output if omitted)
      style : 'bundle.css',        // path of css bundle (not output if omitted)
      template : 'bundle.tmpl',    // path of template bundle (not output if omitted)
    },
    
    browserifyInstance : undefined  // use your own instance of browserify / watchify
    browserifyBundleOptions : {}    // passed through to browserify.bundle()

    watch : false,
}

A parcelify object is returned, which is an event emitter.

p.on( 'done', function(){} );

Called when all bundles have been output.

p.on( 'error', function( err ){} );

Called when an error occurs.

p.on( 'packageCreated', function( package, isMain ){} );

Called when a new package is created. package is a package object as defined in lib/package.js. isMain is true iff the package corresponds to the entry point mainPath.

p.on( 'assetUpdated', function( eventType, asset ){} );

Called when a style asset is updated in watch mode. eventType is 'added', 'changed', or 'deleted', and asset is an asset object as defined in lib/asset.js.

What about client side templates?

Parcelify can compile template bundles using the -t option on the command line and the template key in package.json. However, if you plan to share your packages we recommend against this practice as it makes your packages difficult to consume. Instead we recommend using a browserify transform like node-hbsfy or nunjucksify to precompile templates and require them explicitly from your JavaScript files.

Advanced usage and other assets like images

Parcelify actually supports concatenation of arbitrary asset types. Just add a bundle for that asset type in the bundles key in parcelify options and use the same key to enumerate assets of that type in your package.json. For the case of assets like images, that do not need to be concatenated, you can specify a null path for the bundle. Parcelify will collect all assets of that type but not concatenate them. You can then process the individual assets further using the event callbacks.

Contributors

• James Halliday (Initial design, sage advice, many supporting modules)
• David Beck
• Oleg Seletsky

License

MIT