Asset Pipeline Users Guide

Asset-pipeline now fully supports the commonJs method of loading modules using the require() function. It is important to note, however that these calls are preprocessed outside of a js runtime such that the string being passed to require must be a constant string and not a variable..

Asset-pipeline now supports processing Modern ECMAScript specifications utilizing BabelJs. By default this is disabled for performance but can be enabled by two ways. One is simply by adding .es6 , .es7, .es8 to the end of your javascript file extensions. This can also be done with jsx files (i.e. .jsx.es6) when using jsx-asset-pipeline.

If it is desired to process ALL javascript assets through BabelJs this can be done as well by setting the configuration property in both development runtime and gradle for assets called enableES6:true.

Similar to other packaging libraries like webpack or grunt, asset-pipeline provides a means to require other files or "modules" into your javascript and/or css. We will call these require patterns directives.

In asset-pipeline it is a common pattern to list all requirements of your file at the top in a comments section but this is not required. Example:

Or similarly a CSS file might look like this:

This may look very simple at first but can become really quite powerful. For example, these directives can be nested in other files that you might include. This allows the asset-pipeline to build a dependency-graph, eliminating duplicate requirements, and ensuring everything is loaded in the most optimal order possible.

One other cool aspect of these require directives is the extension is not mandatory. Asset-pipeline will automatically look for any file matching that name (minus the extension) that has a registered AssetFile capable of converting it to the intended target file type. i.e. that Bootstrap directive could be including a LESS file or the javascript could easily include a Coffeescript file.

As of asset-pipeline 2.10.x CommonJs support was added. This is automatically detected in any javascript file and assets are automatically resolved within the project structure of asset-pipeline just like any other directive processor (i.e. var React = require('react');). If your project has conflicts with commonJs it can be turned off by setting the configOptions in gradle and in grails.assets config.

or:

Depending on which framework integration is being used (or even if no framework integration is being used) the project of the asset-pipeline files can slightly differ. However, typically this only affects the source folder location while all other aspects of the project structure remain the same.

By default assets live in the src/assets directory of the project (except in the case of grails where these live in grails-app/assets). However, files should not live at this direct root level and by default asset-pipeline will not detect them if they were. It is a conventional practice that files be organized in one level down subfolders. For example, in a base grails app the following folder structure is used and encouraged:

Asset-pipeline will automatically add any subfolder in the assets directory as a FileResolver. Meaning each folder is treated as a root level resolver path. It is also important to note that asset-pipeline does not actually care what file types go where. This is purely for the organizational benefit of the project.

When a file is referenced via a require directive or web request, the asset-pipeline checks for the file in several locations.

First it tries to find the file relative to the manifest including it. For example "admin/application.js" looking for "table.js"

The first place we will look is within src/assets/javascripts/admin/* We will proceed to do this within all of the asset sub folders across plugins after the main application is searched.

The next place we will look is the root of all src/assets plugin sub folders (e.g. src/assets/*/table.js).

Finally all binary plugins are scanned in the classpath:META-INF/assets folder, classpath:META-INF/static and classpath:META-INF/resources.

In all cases, the applications assets folder takes precedence between the search paths, but plugins get scanned as well.

When the project is built (in Gradle that’s the assetCompile task) these folders are flattened and merged. Meaning this first level subdirectory structure disappears and all files are copied into build/assets. These files also get md5 digested names for cache busting as well as GZIP versions for compressed file serving (except already compressed images).

In a Java based framework any type of WAR or JAR packaging typically gets detected and assets are automatically moved into classpath:assets along with a file classpath:assets/manifest.properties. This manifest is a list of every file that was packaged by the asset-pipeline as the key, and the digested name equivalent as the value. This facilitates easy differential syncing between CDNS (like an s3 bucket for cloudfront) as well as fast and easy generation of ETag headers when serving assets from the application (more on this later).

With all this renaming of assets with digested names as well as slight restructuring between source and build, what happens with url references specified in CSS as well as HTML. This is where some familiar with the Ruby on Rails sprockets based asset-pipeline might remember the need for erb helpers to specify path replacement. The asset-pipeline for the JVM, however, takes a different more automatic approach:

All CSS type files go through a processor called the CssProcessor. This processor looks for any url(../path/to/file.png) type patterns and automatically resolves the asset from the asset-pipeline. If it finds the matching file, the url is automatically replaced with the correct url pattern including the digest name: url(path/file-dadvbfgdaf123e.png).

This relative url replacement is really handy because any external css library that is included in your project (i.e. bootstrap) can be used as is without any need to sift through its code and replace url patterns to match. This feature is also performend on HTML files.

Currently javascript is not scanned for relative path replacement. It is now possible to reference assets from your javascript using a precompiler directive in your code called asset_url. It is not relative and always produces an absolute path response which can be configured via the mapping config option which defaults to 'assets':

Getting started with gradle is very quick and easy. The asset-pipeline-gradle plugin is included in both the gradle plugin repository as well as jcenter and maven. For those of you not familiar with gradle it is a very powerful build tooling system that you should definitely check out.

In its simplest form the build.gradle file might look like this:

Or even simpler:

When this plugin is added a couple tasks and extensions are automatically registered:

Create a folder src/assets and subfolders:

Now assets can be packaged and processed with ease and performance far outpacing other static asset build tooling.

The asset-pipeline gradle plugin provides several very useful configuration options. An extension called assets is automatically added to Gradle when the plugin is applied that provides several options:

The default settings will work for most projects, but if one wanted to add a custom source file location the from directive can be quite useful. Asset-pipeline’s broad Resolver support makes it easy to include assets from a diverse set of locations (even webjars).

A common configuration change for assets may be the includes/excludes patterns. These allow one to specify specific files that should not be individually required or compiled because it does not make sense for them to be individually compiled. In the example above: all .less files are excluded. This does not exclude processing however when a require directive is used making it very easy to only package and bundle assets that the final website needs. It is also important to note that these patterns do not have to be GLOB patterns but can also be regular expressions by prefixing the pattern with regex:. By default all files prefixed with an underscore are automatically excluded from individual processing (similar to SASS).

Some additional options are also provided for configuring what types of output assets are generated:

By default both digested named versions of assets as well as non digested named versions are generated as well as the gzip equivalents. Some frameworks dont actually need the non digested named versions ( ratpack, grails, spring-boot, and servlets). These frameworks take advantage of the manifest.properties file discussed earlier in the documentation to properly map requests for non digested file names to the digested equivalent and preserve compatibility with libraries that may not work well with digested file names.

When working on any jvm based gradle project, the asset-pipeline plugin automatically detects all dependencies on the classpath and scans them for assets. This makes it easy to package assets in shared libraries for multiple apps to use or to even include assets that are included from a webjar dependency.

When using asset-pipeline plugins for processing LESS files or other custom extensions they typically need to be both in the development runtime classpath as well as the build classpath. This is because asset-pipeline provides on the fly asset compilation during development for more rapid iteration cycles. To make this simpler a configuration dependency type is automatically added called assets:

In Grails 3 most assets live in the grails-app/assets directory. This folder is automatically generated for you along with the organizational subdirectories javascripts, images, and stylesheets.

To get started simply add asset-pipeline to your build.gradle file (See Gradle usage). And the grails plugin to the dependencies block:

Asset-Pipeline has several configuration options for use with grails 3. For most cases the configuration options listed in the Gradle guide pertain to grails3. Some subtle differences is the concept of development runtime vs. build time. If you want settings to apply to both development runtime and build time the properties have to be duplicated in your applications application.yml project. This is currently a limitation in how grails reads configuration files and gradle conveys properties.

Most build time options like skipNonDigests or enableGzip will never need specified in this YAML file as they will never be used during development runtime. It is also possible to disable development runtime entirely. In this scenario assets will always be packaged with the application and not monitored for changes unless gradle continuous build is utilized. Simply set assets { developmentRuntime = false} in your build.gradle file.

Example yaml:

Asset pipeline organization occurs within the "grails-app/assets" folder. This folder can exist within both the main application as well as a plugin.

Within the grails-app/assets directory are several subfolders

A common folder that gets added to this set of organization is a "lib" folder. This folder can be useful in organizing third party libraries like jQuery, or Bootstrap.

Asset Pipeline adds a few new taglibs to properly reference your assets. These taglibs automatically handle swapout of cache digest names during production use as well as any custom URL mapping changes.

The primary include tags, as shown above, are quite useful for including your relevant JavaScript or stylesheet files. Notice that you do not have to prefix with '/assets', as this is handled automatically by the tag.

In GSP views, you can also reference images included in the asset-pipeline with the following tag:

Assets can also be referenced within subdirectories if required and simply require the use of the relative path.

It is also possible to return an assetPath as a string for injection in your own tags:

It is also possible to execute a code section only if an asset exists or to simply test for existence

or

In Grails 2 most assets live in the grails-app/assets directory. On any Grails 2.4 or newer application this folder is automatically generated for you along with the organizational subdirectories javascripts, images, and stylesheets.

To get started with asset-pipeline for grails simply add asset-pipeline to the BuildConfig.groovy

Asset-Pipeline has several customizable options to tweak the compiler to suit your needs. Below is a list of the various configuration options and explanations for how to use them.

Asset pipeline organization occurs within the "grails-app/assets" folder. This folder can exist within both the main application as well as a plugin.

Within the grails-app/assets directory are several subfolders

A common folder that gets added to this set of organization is a "lib" folder. This folder can be useful in organizing third party libraries like jQuery, or Bootstrap.

Asset Pipeline adds a few new taglibs to properly reference your assets. These taglibs automatically handle swapout of cache digest names during production use as well as any custom URL mapping changes.

The primary include tags, as shown above, are quite useful for including your relevant JavaScript or stylesheet files. Notice that you do not have to prefix with '/assets', as this is handled automatically by the tag.

In GSP views, you can also reference images included in the asset-pipeline with the following tag:

Assets can also be referenced within subdirectories if required and simply require the use of the relative path.

It is also possible to return an assetPath as a string for injection in your own tags:

It is also possible to execute a code section only if an asset exists or to simply test for existence

or

In Micronaut assets live in the same place as a standard gradle implementation src/assets directory. This folder should contain organizational subdirectories javascripts, images, and stylesheets. Another option is to use a standard folder within assets called something like src/assets/frontend. Useful if simply using asset-pipeline to render and properly digest generated apps from React or other view frameworks.

To get started simply add asset-pipeline to your build.gradle file (See Gradle usage). And the micronaut plugin to the dependencies block:

By default, the asset-pipeline gradle plugin will automatically attach itself to the shadowJar gradle task as a build dependency. The development runtime will also auto engage so long as no assets/manifest.properties file exists on the classpath.

In Ratpack assets live in the same place as a standard gradle implementation src/assets directory. This folder should contain organizational subdirectories javascripts, images, and stylesheets.

To get started simply add asset-pipeline to your build.gradle file (See Gradle usage). And the ratpacks plugin to the dependencies block:

Finally the AssetPipelineModule needs added to the Ratpack Registry.

This module does support a few configuration options and due to how the runtime works the sourcePath does need to be specified depending on if ratpack is being run in development from an IDE or gradle directly.

By default a Handler will be registered to the url /assets but it is also possible to simply use the AssetPipelineHandler directly or even change the base mapping config as seen in the example above.

In Spring Boot assets live in the same place as a standard gradle implementation src/assets directory. This folder should contain organizational subdirectories javascripts, images, and stylesheets.

To get started simply add asset-pipeline to your build.gradle file (See Gradle usage). And the ratpacks plugin to the dependencies block:

It is also necessary to add ComponentScan to your application class in order for the asset-pipeline plugin to properly initialize.

By default a servlet filter will be registered to the url /assets from which all assets will be served.

With the LESS module it is easy to automatically compile LESS files down to the native browser CSS format. By default the less-asset-pipeline plugin takes advantage of Less4j for highly performant LESS compilation. If the standard compiler is desired this can also be enabled however it is dramatically slower due to running in a javascript environment.

The SASS module provides easy processing and implementation of scss and sass files. It uses libsass for highly performant compiling of SASS files and automatically handles asset resolution correctly.

The Coffee Asset-Pipeline module provides coffeescript compilation support for the jvm based asset-pipeline. Simply add this file to your buildscript classpath or development environment and they are automatically processed.

The AssetFile definition is where our journey begins. This is the defining file for various file types. Without this definition, the asset-pipeline will treat an unknown file type as a standard passthrough resource. As an example, lets first look at the CssAssetFile definition.

This file definition is pretty short but allows us to define some very useful information. First, we look at the static definitions at the top of the class. These static definitions are fairly easy to meta-override with Groovy and add additional processors or adjust with added plugins.

The contentType property is used to match a file definition with an incoming file request. When the browser requests a text/css content-type file , this file is matched and files matching this definition are scanned. The extensions list tells asset-pipeline which file extensions to scan through and match. In this case it is just 'css', but in the case of LESS for example, we may be looking for extensions less, or css.less.

The compiledExtension property tells asset-pipelines precompiler what the final file extension should be.

Finally, the processors array determines the list of processors that need be run on the file contents before returning a result. This array is executed in order. In this case, we have the CssProcessor (a processor for converting the relative image paths and replacing with their cache digested version).

Processors are where the real power of asset-pipeline comes into play. These are the driving force behind making compileable assets such as LESS, and CoffeeScript first class citizens. Gone is the need to run a compiler on the side, and gone is the delay between making changes in development.

A Processor is an implementation of the Processor interface via the AbstractProcessor class. It must have a constructor with an AssetCompiler argument, and it must have a process method. The rest is up to the developer. The reason the AssetCompiler is passed is for giving the processor access to manipulate the precompiler phase. If a null precompiler is passed, than development mode is assumed and the processor can infer that. An example use case for this is the SassProcessor in the SASS/SCSS Asset Pipeline Plugin. Image sprite generation causes additional image files to be created that need added to the list of files to process.

Above is an excerpt of the CoffeeScriptProcessor plugin. This plugin takes advantage of RhinoJS to use the CoffeeScript compiler and provide the application with direct support for CoffeeScript files. The process method takes an input, as well as a reference to the asset file definition, and returns a result. To use your processor simply add it to your 'static processors' array on the AssetFile definition.

The LESSProcessor was not used in this example as it’s more complicated due to supporting the @import LESS directive and cache dependencies on the cache manager. However, it is a great example to look at and highly recommended.

Currently, PostProcessor extensibility is not available. This is currently a feature we are implementing to provide easier dropin for custom minifiers and compressors.