Blend¶
Merge, analyze, and optimize client-side assets for web applications and static web sites.
Introduction¶
Blend was inspired by the asset pipeline introduced in Ruby on Rails 3.1 (http://guides.rubyonrails.org/asset_pipeline.html)
You can create a configuration file to control how Blend analyzes, merges, and optimizes your files, but you don’t have
to. Without a configuration file, running blend
in your project directory will:
- Search for any javascript or css files containing blend formatted require statements.
- Run JSLint on the javascript files.
- Recursively merge required files.
- Write the merged files to the
output
directory. - Write the merged files to the
output
directory. - Use the YUI compressor to create minified versions of the files in the
output
directory.
Installation¶
From the Python Package Index¶
pip install blend
From Source¶
git clone git://github.com/azavea/blend.git
cd blend
python setup.py install
Usage¶
The blend
command line tool is designed to process a directory full of files or individually specified files. Given
the following directory structure:
project
lib
jquery.min.js
src
app.js
And the following app.js
:
/* app.js */
//= require jquery
var app = {};
Running blend
in the project
directory will result in the following directory tree structure:
project
lib
jquery.min.js
output
app.js
app.min.js
src
app.js
Where the content of project/output/app.js
is project/lib/jquery.min.js
merged into project/src/app.js
and
project/output/app.min.js
is the minified version of project/output/app.js
Command Line Options¶
Output¶
-o OUTPUT, --output=OUTPUT
Where the file output will be written. The default is a directory at the root of the
project directory named output
Path¶
-p PATH, --path=PATH
A directory to be searched for required files. Multiple directories can specified by repeating the flag. If you do not specify any directory with the PATH flag then only the working directory will be searched for required files.
Skip Working Directory¶
-s, --skipcwd
Exclude the current working directory from the requirement search paths.
Warning
If you do not specify any paths using the -p,–path option and you also specify the -s,–skipcwd option then Blend will have no directories in which to search for required files and will be unable to merge your code.
Specify A Configuration File¶
-c, --config
Specify a JSON confguration file that describes the analyzers and minifiers to be used.
Adding Requirements To Files¶
For javascript files, Blend uses the same require syntax as the Rails 3.1 asset compiler.:
//= require jquery
For CSS files, Blend will recognize comment requires:
/*= require control */
Blend will also recognize @import url("...")
statements in CSS files and treat them as require statements:
@import url("control.css")
Note
require
comments reference other files using a “base name.” You must not include the file extension or version numbers or min
suffixes. Blend strips these suffixes out of the file name when searching for files to satisfy a requirement.
How Blend Satisfies Requirements¶
By default, Blend recursively searches in the directory from which it is run for files to satisfy requirements. You
can suppress this behavior with the -s, --skipcwd
argument and you can add additional search paths using the
-p, --path
argument.
Searching By Base Name¶
Given the following file:
/* app.js */
//= require jquery
var app = {};
When you run:
blend app.js
Blend will search for a file with a base name of jquery
and a .js
extension. Any of the following files would
satisfy this requirement:
JQUERY.js
jquery.javascript
jQuErY.js
jquery-1.2.3.js
JQUERy.min.js
jquery-1.2.3-min.js
None of these files would satisfy this requirement:
jjquery.js
jquery123.js
jquery.jscript
jquery-minified.js
Search Priority¶
Blend will prefer to satisfy a requirement with a file in the same directory as the requiring file or a subdirectory
of the requiring file. Given this app.js
:
/* app.js */
//= require component
var app = {};
and this directory structure:
project
lib
component.js
src
app.js
components
component.js <- this file will be merged with app.js
The component.js
file nested under src/components
will “win.”
Analyzers¶
By default, Blend runs JSLint on all the javascript files it processes. This can generate failures when you are merging
in 3rd party libraries that do not pass JSLint. To get around this problem, the default JSLint analyzer is configured
to ignore any files that are under a lib
directory at the root of the project folder.
Given the following app.js
:
/* app.js */
//= require jquery
var app = {};
Running blend
in this directory structure:
project
src
app.js
jquery.min.js
Will fail because the minified JQuery library will not pass a JSLint check. However, if you move the JQuery file so the directory structure looks like this:
project
lib
jquery.min.js
src
app.js
Then running blend
will succeed because the JSLint analyzer will skip over project/lib/jquery.min.js
.
Configuring Blend¶
Blend can read configuration options from a JSON formatted file. Here is what the default configuration looks like:
{
"analyzers": {
"javascript": [
{
"name": "blend.JSLintAnalyzer",
"skip_list": [
"bin"
]
}
]
},
"minifiers" {
"javascript": {
"name": "blend.YUICompressorMinifier"
},
"css": {
"name": blend.YUICompressorMinifier"
}
}
}
Blend can load configuration files in two ways:
- From
{current working directory}/.blend/config.json
- From a file specifed with the
-c,--config
command line argument
A config file specified with the -c,--config
command line argument will override a .blend/config.json
file.