parcelify - npm Package Compare versions

Comparing version 0.6.7 to 0.7.0

bin/cmd.js

@@ -13,8 +13,8 @@ #!/usr/bin/env node
 			cssBundle : "c",
-			tmplBundle : "t",
+			transform : "t",
 			watch : "w",
-			debug : "d",
+			maps : "m",
 			help : "h"
 		},
-		boolean : [ "watch", "help", "debug" ]
+		boolean : [ "watch", "help", "maps" ]
 	}
@@ -34,4 +34,5 @@ );
 var mainPath = resolvePath( argv._[0] );
+var defaultTransforms = argv.transform;
 var watch = argv.watch;
-var debug = argv.debug;
+var maps = argv.maps;
 
@@ -49,4 +50,5 @@ if( ! mainPath ) {
 	},
+	defaultTransforms : defaultTransforms,
 	browserifyBundleOptions : {
-		debug : debug
+		debug : maps
 	},
@@ -53,0 +55,0 @@ watch : watch

bin/help.txt

@@ -10,11 +10,8 @@
 
-  --tmplBundle, -t  Parcelify can optionally bundle your client side templates as well. Template 
-                    assets are specified in the exact same way as style assets, just using a 
-                    template key in package.json instead of a `style` key.
-
   --watch, -w       Watch mode - automatically rebuild bundles as appropriate for changes.
 
-  --debug, -d       Enable source maps that allow you to debug your js files separately.
-                    (Passed through directly to browserify.)
+  --maps, -m        Enable JavaScript source maps in js bundles (for dev mode).
 
+  --transform, -t   Name or path of a default transform. (See discussion of `defaultTransforms` option.)
+
   --help, -h        Show this message

index.js

@@ -34,2 +34,5 @@ var path = require('path');
 
+		defaultTransforms : [],
+		packageTransform : undefined,
+		
 		watch : false,
@@ -96,4 +99,7 @@
 	var mainParcelMap;
-	var packageFilter = options.browserifyBundleOptions.packageFilter;
+	var packageFilter;
 
+	packageFilter = this._createBrowserifyPackageFilter( options.packageTransform, options.defaultTransforms );
+	options.browserifyBundleOptions.packageFilter = packageFilter;
+
 	var parcelMapEmitter = parcelMap( browerifyInstance, { keys : assetTypes, packageFilter : packageFilter } );
@@ -156,5 +162,2 @@
 	} );
-	
-	// get things moving. note we need to do this after parcelMap has been called with the browserify instance
-	//jsBundleStream = browerifyInstance.bundle( options.browserifyBundleOptions ); //.pipe( through2() );
 };
@@ -242,2 +245,32 @@
 	} );
-};
+};
+
+
+Parcelify.prototype._createBrowserifyPackageFilter = function( existingPackageFilter, defaultTransforms ) {
+	var packageFilter = existingPackageFilter;
+
+	if( ! packageFilter ) packageFilter = function( pkg ){ return pkg; };
+
+	// make sure we have a default transforms inplace
+	function ensureDefaultTransform( pkg ) {
+		if( ! pkg.transforms ) pkg.transforms = [];
+		return pkg;
+	}
+
+	// make another transform that curries the browserify transforms to our generalized transform key
+	function curryBrowserifyTranforms( pkg ) {
+		if( pkg.browserify && pkg.browserify.transform && _.isArray( pkg.browserify.transform ) )
+			pkg.transforms = pkg.transforms.concat( pkg.browserify.transform );
+
+		return pkg;
+	}
+
+	function applyDefaultTransforms( pkg ) {
+		if( pkg.transforms.length === 0 )
+			pkg.transforms = defaultTransforms;
+
+		return pkg;
+	}
+
+	return _.compose( applyDefaultTransforms, curryBrowserifyTranforms, ensureDefaultTransform, packageFilter );
+};

lib/package.js

@@ -272,3 +272,5 @@ var path = require('path');
 			async.map( transformNames, function( thisTransformName, nextTransform ) {
-				resolve( thisTransformName, { basedir : packageJson.path }, function( err, modulePath ) {
+				if( _.isFunction( thisTransformName ) ) return nextTransform( null, thisTransformName );
+
+				resolve( thisTransformName, { basedir : packageJson.__path }, function( err, modulePath ) {
 					if( err ) return nextTransform( err );
@@ -275,0 +277,0 @@

package.json

 {
   "name": "parcelify",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "Create css bundles from npm packages using the browserify dependency graph.",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -5,4 +5,4 @@ # Parcelify
 
-* Use npm packages for reusable interface components.
-* Easily include transforms for scss, less, etc. on a per-package basis.
+* Use npm packages for interface components with styles and templates.
+* Efficiently transform scss / less to css, coffee to JavaScript, etc. using streams.
 * Rebuild bundles automatically with watch mode.
@@ -62,10 +62,9 @@
 
---tmplBundle, -t  Path of optional template bundle (see below discussion on client side templates).
+--jsBundle, -j    Path of the JavaScript bundle (i.e. browserify's output).
 
 --watch, -w       Watch mode - automatically rebuild bundles as appropriate for changes.
 
---jsBundle, -j    Path of the JavaScript bundle (i.e. browserify's output).
+--maps, -m        Enable JavaScript source maps in js bundles (for dev mode).
 
---debug, -d       Enable source maps that allow you to debug your js files separately.
-                  (Passed through to browserify.)
+--transform, -t   Name or path of a default transform. (See discussion of `defaultTransforms` option.)
 
@@ -75,8 +74,7 @@ --help, -h        Show this message
 
-## package.json
+## Tranforms
 
-Two keys are special cased in package.json files.
+### Local (package specific) transforms
 
-* 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](https://github.com/substack/module-deps#transforms) to be applied to assets.
+The safest and most portable way to apply transforms like sass -> css or coffee -> js is using the `transforms` key in a package's package.json. The key should be an array of names or file paths of [transform modules](https://github.com/substack/module-deps#transforms). For example,
 
@@ -86,7 +84,7 @@ ```
   "name": "my-module",
-  "description": "Example package.json for hypothetical myModule.",
+  "description": "Example module.",
   "version": "1.5.0",
   "style" : "*.scss",
   "transforms" : [ "sass-css-stream" ],
-  "devDependencies" : {
+  "dependencies" : {
     "sass-css-stream": "0.0.1"
@@ -97,2 +95,25 @@ }
 
+All transform modules are called on all assets plus JavaScript files. It is up to the transform module to determine whether or not it should apply itself to a file (usually based on the file extension).
+
+### Application level (global) transforms
+
+You can apply quasi-global, application level transforms using the `defaultTransforms` option.
+
+```
+$ parcelify main.js -c bundle.css -t "sass-css-stream"
+```
+
+Because such application level transforms can easily conflict with local transforms, the transforms in `defaultTransforms` are only applied to packages that to not have their own local transforms. If you need more control over which application level transforms are applied to what packages, you can use the `packageTransform` option to insert transforms into the package.json of specific packages.
+
+```javascript
+c = parcelify( mainPath, {
+    packageTransform : function( pkg ) {
+        if( ! shouldApplyAppTransforms( pkg ) ) return pkg;
+
+        pkg.transforms = ( pkg.transforms || [] )
+            .concat( [ 'sass-scc-stream' ] );
+    }
+} );
+```
+
 ## API
@@ -102,18 +123,17 @@
 
-`mainPath` is the path of the JavaScript entry point file. options are as follows:
+`mainPath` is the path of the JavaScript entry point file. Options may contain:
 
+* `bundles` - A hash that maps asset types to bundle paths. You will generally just want an entry for a `script` bundle (which is special cased for the browserify bundle) and a `style` bundle, but arbitrary asset types are supported. Default:
+
 ```javascript
-{
-    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,
+bundles : {
+  script : 'bundle.js',  // send browserify output here (special cased)
+  style : 'bundle.css'   // bundle `style` assets and output here
 }
 ```
+* `defaultTransforms` (default: undefined) - An array of [transform modules](https://github.com/substack/module-deps#transforms) names / paths or functions to be applied to packages in which no local transforms are specified. Can be used for quasi-global transforms (without the risk of conflicting with packages that use their own transforms).
+* `packageTransform` (default: undefined) - A function that transforms package.json files before they are used. The function should be of the signature `function( pkgJson )` and return the parsed, transformed package object. This feature can be used to add default values to package.json files or alter the package.json of third party modules without modifying them directly.
+* `browserifyInstance` (default: undefined) - Use your own instance of browserify / watchify.
+* `browserifyBundleOptions` (default: {}) - Passed through directly to browserify.bundle().
+* `watch` : Watch mode - automatically rebuild bundles as appropriate for changes.
 
@@ -134,9 +154,9 @@ A parcelify object is returned, which is an event emitter.
 
-## What about client side templates?
+## Client side templates and other assets
 
-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](https://github.com/epeli/node-hbsfy) or [nunjucksify](https://github.com/rotundasoftware/nunjucksify) to precompile templates and `require` them explicitly from your JavaScript files.
+Parcelify actually supports concatenation / enumeration of arbitrary asset types. Just add a bundle for an asset type in the `bundles` option and use the same key to enumerate assets of that type in package.json.
 
-## Advanced usage and other assets like images
+A tempting use case for this feature is client side templates - just include a `template` key in package.json and a corresponding entry in the `bundles` option, and you have a bundle of client side templates. 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](https://github.com/epeli/node-hbsfy) or [nunjucksify](https://github.com/rotundasoftware/nunjucksify) to precompile templates and `require` them explicitly from your JavaScript files.
 
-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.
+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.
 
@@ -143,0 +163,0 @@ ## Contributors

test/test.js

@@ -146,3 +146,3 @@ var test = require('tape');
 
-// test a parcel with no package.json
+// default transforms
 test( 'page6', function( t ) {
@@ -159,3 +159,5 @@ t.plan( 2 );
 			style : path.join( dstDir, 'bundle.css' )
-		}
+		},
+
+		defaultTransforms : [ require( 'sass-css-stream' ) ]
 	};
@@ -167,6 +169,2 @@
 
-	p.on( 'packageCreated', function( thePackage ) {
-		thePackage.addTransform( require( 'sass-css-stream' ) );
-	} );
-
 	p.on( 'done', function() {
@@ -173,0 +171,0 @@ t.deepEqual(

New alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

43856

increased by5.9%

Lines of code

815

increased by2.39%

Number of lines in readme file

165

increased by13.79%

Worsened metrics

Number of package files

32

decreased by-17.95%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes