Asset Pipeline Plugin

19 votes
Dependency:
compile ":asset-pipeline:1.9.4"

 Documentation  Source  Issues

Summary

The Asset-Pipeline is a plugin used for managing and processing static assets in Grails applications. Asset-Pipeline functions include processing and minification of both CSS and JavaScript files. It is also capable of being extended to compile custom static assets, such as CoffeeScript.

Installation

plugins {
   compile ':asset-pipeline:1.9.4'
}

Description

Asset Pipeline is intended to replace the defacto Grails equivalent (`resources-plugin`) with a more efficient, developer friendly architecture (similar to rails asset-pipeline). The asset-pipeline levereges the latest in minification (UglifyJS) to reduce your asset sizes as much as possible. A few differences between the resources plugin and asset-pipeline include:
  • On the fly processing - No more waiting for your assets to reload after making a change
  • Compiled assets on war create - No more hanging up application boot times while processing files. `grails war`
  • Reduced Dependence - The plugin has compression, minification, and cache-digests built in.
  • Easy Debugging - Makes for easy debugging by keeping files seperate in development mode.
  • Simpler manifests and taglibs - Read on for more information.

Usage

Asset-Pipeline automatically creates a series of folders within your grails-app directory:
grails-app/assets/javascript , grails-app/assets/images, grails-app/assets/stylesheets

Place your static assets in those directories and simply include them into your layouts. Asset pipeline supports setting up manifests using these files.

Example 'grails-app/javascripts/application.js':

//This is a javascript file with its top level require directives
//= require jquery
//= require app/models.js
//= require_tree views
//= require_self

console.log("This is my javascript manifest");

The above is an example of some of the require directives that can be used. Custom directives can be created and overridden into the DirectiveProcessor class.

Optionally, assets can be excluded from processing if included by your require tree. This can dramatically reduce compile time for your assets. To do so simply leverage the excludes configuration option:

grails.assets.excludes = ["tiny_mce/src/*.js"]

Including Assets in your Views

Asset pipeline provides several new tag libs for including javascript and css into your gsp files.

Example:

<head>
	<asset:javascript src="application.js"/>
	<asset:stylesheet href="application.css"/>
</head>

These helpers will automatically adjust to point to the cache-digested versions of the files when running in a non-development environment.

NOTE: In development mode your stylesheets and javascripts will be included as individual script tags. This is intended to make it easier for debugging. Bundling is enabled in all other environments and can be forced in development mode by adding

grails.assets.bundle=true
to your Config.groovy.

Precompiling For Production

Assets are now compiled upon war generation into target/assets. This can be done by running:
grails war

During war build your assets are also minified using UglifierJs. To disable this feature you can add the following option to your config:

grails.assets.minifyJs = false

Serving Assets from External Storage Directory

Asset Pipeline can be configured to copy your assets files out into an external storage path. This can be useful for setting up your web server (i.e. Nginx) to directly server your static assets. To do so, simply define a config variable in your Config.groovy environment block

environments {
	production {
		grails.assets.storagePath = "/full/path/to/storage"
	}
}

It is also possible to configure a custom CDN asset url for serving this assets:

environments {
	production {
		grails.assets.url = "http://s3.amazonaws.com/asset-pipe/assets"
	}
}

Custom Files

Asset Pipeline uses a Class type called AssetFile. These AssetFiles are included into the AssetHelper.assetSpecs static array. By default, this plugin comes with a JsAssetFile, and CssAssetFile. These define the match pattern syntax for understanding requires directives, known extensions, processors, and content-type. The application bases its file look-up on content-type of the request rather than extension. This allows the user to, for example, define a CoffeeAssetFile with the javascript content type and a request to localhost/assets/app.js would be able to find assets/app.coffee.