Bindep NPM | npm.io

Bindep

It is a grunt tool for binding bower or local dependencies to your source code. It introduces few little concepts for its working:

Why bindep?

Bower created a repository very usefull for handling components but the model designed is too much simple. In many real cases you can't process automatically because the information inside is not sufficient: for example you can't process a project in which you want define some optional parts to inject just in specific cases, it is difficult to place correctly resources used inside a project in a specific position defined by software designer,you can't use a preprocessor for creating source code specific for a use case. Bindep extends the bower model permitting to use bower repository also when you want design complex project.

It is born (original name was grunt-resourcesbinder) for my needs using a high modularity level in my projects.Bindep for working extends the bower json definition with other properties.Bottom you can see a example about the bower.json containing new properties:

{
  "name":"example",
  "main":["core.js","core.css"],
  "configurator":["grunt dist"], // if present it execute the command lines for configurating the component
  "resources": { // you can remove if empty
  "mp3":"audio1.mp3",
  "font":"font/*"
  },
  "defaults":{ // you can remove if empty
"enablePreprocessor":true,// default is false
"preprocessorContext":{"c":4},//default context for preprocessor
"components":{ // this part override component definition
"modules":{
"filedetector":["image"] //submodules used in the dependencies
}
},	
"modules":['preview'] // default modules used in the current bower component
},
  "modules":{ // you can remove if empty
   
   "preview":{
   "main":["js/preview.js"],
   "dependencies":{ "moment":"^1.0.0" },
    "imports":{ "ababa":"^1.0.0" },//it permits to add a source in the folder withtout inject linking in the template (usefull for dynamic source loading)
   "resources":{
   "mp3":["audio2.mp3","audio3,mp3"],
   "require":[....]
   }
   },
   
     "dependencies":{ "jquery":"^3.0.0" }
   
   }

Bindep is conversative so you can use old bowers components if they don't need additional info(adding preprocessor macros pay attention to the way in which are written) Less file will be converted automatically in a css file. For example:

{
  "name": "bootstrap",
  ....
  "main": [
    "less/bootstrap.less",
    "dist/js/bootstrap.js"
  ],
 ....
  "dependencies": {
    "jquery": "1.9.1 - 3"
  }
}

Getting Started

Install the module with npm:

$ npm install --save bindep

Install your bower dependencies (if you haven't already):

$ bower install --save jquery

Insert placeholders in your code where your dependencies will be injected:

<html>
<head>
  <!-- @bind:css linked separated uglified 
       jquery
  --> 
</head>
<body>
  <!-- @bind:js linked separated uglified 
       jquery
       moment
       
  -->
</body>
</html>

The complete syntax is

@bind:[<filetype>] <linked|inline>  <aggregated|separated>  [minified|uglified]

The options mean: linked: it replace the link if the corrispondent dependency using the link replacement, inline: it replace directly the all sources mentioned using source replament, aggregated: it aggregate all dependencies, separated : it handles each dependency separately. In the following lines of this block you must insert all the top dependencies (one for every line) with this syntax:

<package_name><modules><search> <nodeps> <nounique> <preprocess ( [<name>:<value>]* )>

where modules is optional and has this syntax :

<( <module1> , <module2> , ...)>

where search is optional and has this syntax :

<[<op> "<[filter]>" ]>

where op comparator is :

	== : equals
	!= : not equals
	=^ : starts with
	!^ : not starts with
	=$ : ends with
	!$ : not ends with
	=? : contains 
	!? : not contains
	=~ : match the filter
	!~ : not match the filter

where

nodeps is optional and force to not inject the dependencies
nounique is optional and permits to repeat the same package in the template.
preprocess is optional and permits to preprocess the source files passing options.

Bottom a example about filtering and about modules setting.

<!-- @bind:js inline aggregated uglified
			html5shiv
			respond (res1,res2)
 			frontend-miscellaneous[=$ "browser-extension.js"]

-->

Bottom you can see a example in which you active the preprocessor for the component 'example' and you pass to it 3 properties

<!-- @bind:js inline aggregated uglified
            example2 preprocess (mode:1  platform: "mobile" withColours: true )
-->

The optional parameters search and nodeps might be used just if necessary , for example where a external bower package contains different versions in the same package or optional dependencies.

The sub dependencies of the package are automatically injected if 'nodeps' parameter is not set. The filter is optional and permits to filter the resources of that package. Let bind work its magic:

<html>
<head>
 <link href="/css/jquery.css">

</head>
<body>
  <script src="/js/jquery.js"></script>
  <script src="/js/moment.js"></script>
</body>
</html>

Build Chain Integration

Grunt

Bindep uses grunt. You have to insert a Gruntfile.js file in your root project folder. In this file you set you setup your project configuration. Essentially you can set:

paths where bindep reads template files
local dependencies present in your projects, if you need
development:if true minimization and aggregations of attachments is skipped
attachments: folders where bindep searchs files, target folder where bindep put the final output,the type of replament you want
resources: for each resource type you define the folder where bind save the final output You can pass other options not usually necessary as additional converters (it is present just less converter actually),a custom package handler for fixing errors in external bower component,..... A gruntfile.js example:

module.exports = function(grunt) {
var project=(grunt.option( "project" )==undefined)?'':grunt.option( "project" );
grunt.initConfig({
// Before generating any new files, remove any previously-created files.

bindep: {
default_options: {
localDependencies:[{
	name:"fileutils",
	main:"src/main/js/fileUtils.js"
    },
    {
    name:"layout",
    main:"src/main/css/layout.css"
    }
       
],
packageHandler:function(n,mains,deps){// fix qtip2 error
if (n=='qtip2') {

	mains.push('jquery.qtip.css');
}else if (n=='typeahead.js') {

	mains.push('bloodhound.js');
}

},
templates:[{target:'target/'+project+'/WEB-INF/ftl/',extension:'ftl',sources:['src/main/ftl/**/*.ftl']},{target:'target/'+project+'/WEB-INF/js/',sources:['src/main/js/templates/**/*.js'],linksOnDebug:false}],
development:grunt.option( "dev" )!==undefined,
shortLinks:true,

attachments:{
js: {replacement:{link:'<script src="<@utils.url\'/js/{{file}}\'/>"></script>',inline:'<script>{{source}}</script>'},target:'target/'+project+'/WEB-INF/js/'},
css:{replacement:{link:'<link rel="stylesheet" href="<@utils.url\'/css/{{file}}\'/>"  media="screen" />',inline:'<style>{{source}}</style>'},target:'target/'+project+'/WEB-INF/css/'}
},
resources:{
mp3:{target:'target/'+project+'/WEB-INF/mp3/'},
img:{target:'target/'+project+'/WEB-INF/img/'},
font:{target:'target/'+project+'/WEB-INF/fonts/'}
}

}
}
});

	grunt.loadNpmTasks('bindep');
	// Default task(s).
	grunt.registerTask('default', ['bindep' ]);

};

In console you can type

grunt -dev

Pay attention to pass -dev, because the minification can take time.

You can find a example working at https://github.com/publicocean0/qrcodereader/tree/master/test

Maven

If you use maven, for building a web project , you can add the plugin frontend-maven-plugin permitting to call bindep before creating a war. A example about configuration is :

		<plugin>
						<groupId>com.github.eirslett</groupId>
						<artifactId>frontend-maven-plugin</artifactId>
						<version>1.0</version>
						<executions>
							<execution>
								<id>npm install</id>
								<goals>
									<goal>npm</goal>
								</goals>
								<configuration>
									<arguments>install</arguments>
								</configuration>
							</execution>
							<execution>
								<id>bower install</id>
								<goals>
									<goal>bower</goal>
								</goals>
								<configuration>
									<arguments>install</arguments>
								</configuration>
							</execution>
							<execution>
								<id>grunt build</id>
								<goals>
									<goal>grunt</goal>
								</goals>
								<configuration>
									<arguments>--no-color</arguments>
									<arguments>--project=${project.artifactId}</arguments>
									<arguments>--dev</arguments>
								</configuration>
							</execution>
						</executions>
					</plugin>