The core implementation of the asset pipeline for the jvm
JavaScript HTML Groovy CSS Java Ruby Other
Latest commit ba28bd1 Aug 20, 2016 @Prototik Prototik committed with davydotcom Replace closure-compile with unshaded artifact due to classloading is…
…sues (commonly with Gson) (#117)
Failed to load latest commit information.
asset-pipeline-classpath-test fixed a lot of features in gradle integration, added new config optio… Apr 22, 2016
asset-pipeline-core Replace closure-compile with unshaded artifact due to classloading is… Aug 20, 2016
asset-pipeline-docs updating release docs and fixing jsx parser, also improving commonjs … Aug 14, 2016
asset-pipeline-gradle Merge pull request #89 from daspilker/process-resources May 22, 2016
asset-pipeline-grails fixing cache digest headers issue with no-cache and grails Aug 5, 2016
asset-pipeline-servlet replaced def with strong types May 30, 2016
asset-pipeline-site updating release docs and fixing jsx parser, also improving commonjs … Aug 14, 2016
asset-pipeline-spring-boot final local variables May 30, 2016
coffee-asset-pipeline fixing target java version compatibility Jul 22, 2016
compass-asset-pipeline fixing target java version compatibility Jul 22, 2016
ember-asset-pipeline fixing target java version compatibility Jul 22, 2016
gradle/wrapper significant documentation update, fix for less4j 1.15.0 and update to… Oct 19, 2015
handlebars-asset-pipeline fixing target java version compatibility Jul 22, 2016
jsx-asset-pipeline updating release docs and fixing jsx parser, also improving commonjs … Aug 14, 2016
less-asset-pipeline updating release docs and fixing jsx parser, also improving commonjs … Aug 14, 2016
ratpack-asset-pipeline cleanup May 22, 2016
sass-asset-pipeline fixes for sass Jul 22, 2016
.gitignore deploying to morpheus web Apr 27, 2016
.travis.yml updating build info and fixing sass Oct 10, 2015
Readme.markdown fixing bugs in the jflex dependency Aug 5, 2016
asset-pipeline-core.ipr adding plugin search and api docs in ascii doc May 23, 2016
asset-pipeline.iws more speed in response rendering, fixes to date modified now in respo… Mar 4, 2016
build.gradle Replace closure-compile with unshaded artifact due to classloading is… Aug 20, 2016
gradlew working on sass Oct 10, 2015
gradlew.bat added gradle wrapper for testing Dec 1, 2014
settings.gradle woah, we actually have support for jsx now and ecmascript 6 Jul 28, 2016

Readme.markdown

Asset Pipeline Core

Build Status

Overview

The Asset-Pipeline is a plugin used for managing and processing static assets in JVM applications primarily via Gradle (however not mandatory). 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 or LESS.

Features:

  • Asset Bundling
  • Extensible Modules (Supports LESS,Handlebars,Coffeescript, Ember-Handlebars, SASS) via other modules.
  • Cache Digest Names (Creates cache digested names and stores aliases in a manifest.properties)
  • Js Minification
  • Js SourceMap Generation
  • Css Minification / Relative Path assertion
  • File Encoding Support
  • GZIP File Generation
  • Last-Modified Header

Documentation

Gradle Usage

If using gradle, this plugin adds a series of tasks directly to your gradle plugin. All you have to do is apply plugin:'asset-pipeline' after confirming this is in the classpath of your buildscript block. i.e.:

//Example build.gradle file
buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
    mavenCentral()
  }
  dependencies {
    classpath "com.bertramlabs.plugins:asset-pipeline-gradle:2.10.1"
  }
}

apply plugin: 'com.bertramlabs.asset-pipeline'

assets {
  minifyJs = true
  minifyCss = true
  enableSourceMaps = true
  configOptions = [:]

  minifyOptions = [
    languageMode: 'ES5',
    targetLanguage: 'ES5', //Can go from ES6 to ES5 for those bleeding edgers
    optimizationLevel: 'SIMPLE',
    angularPass: true // Can use @ngInject annotation for Angular Apps
  ]

  includes = []
  excludes = ['**/*.less'] //Example Exclude GLOB pattern

  //for plugin packaging
  packagePlugin=false //set to true if this is a library

  //developmentRuntime can be turned off
  developmentRuntime=true

  //if you want to customize the jar task this task runs on you can specify a jarTaskName
  jarTaskName=null

  // Can add custom asset locations (directories or individual jar files)
  from '/vendor/lib'
  from '/path/to/file.jar'
}

dependencies {
  // Example additional LESS support
  // assets 'com.bertramlabs.plugins:less-asset-pipeline:{}'
}

Now that you have your build.gradle files. All you need to do is put files in your projects src/assets/javascripts, src/assets/stylesheets, src/assets/images, or whatever subdirectory you want. When you run gradle assetCompile these files will be processed and output into your build/assets folder by default.

Thats about all there is to it. Now you can use gradle to handle processing of all your client side assets.

Advanced Usage

The core part of asset-pipeline is rather agnostic to whichever implementation you want to use, be it servlet based, netty based, or whatever else you want to do. The recommended use case for this aspect of the plugin is to integrate with other plugins that are capable of being scoped to specific frameworks. Currently the best example of the use case for the asset-pipeline plugin is in the Grails framework.

The core plugin provides interfaces for asset resolution, processing, and compiling into a target directory. You can register resolvers in the AssetPipelineConfigHolder to essentially add scan paths for your static assets. This includes both File System support as well as Jar file support (ClassPathResolver coming soonish)

import asset.pipeline.*
import asset.pipeline.fs.*

def fsResolver = new FileSystemAssetResolver('application','assets')
def jarResolver = new JarAssetResolver('application','/path/to/file.jar','META-INF/assets')
AssetPipelineConfigHolder.registerResolver(fsResolver)
AssetPipelineConfigHolder.registerResolver(jarResolver)

As can be seen above, we have registered 2 examples of implementations of the AssetResolver interface

Now we can take advantage of asset-pipeline endpoints to fetch files for development mode as well as compiling files for production.

To Fetch a File in Development mode simply use the following endpoint:

class AssetPipeline {
    static byte[] serveAsset(uri, contentType = null, extension = null, encoding = null) {

    //Returns a dependency list of your asset (based on require directives)
    static def getDependencyList(uri, contentType = null, extension = null)

    //For skipping directive processing (when requiring files individually)
    static byte[] serveUncompiledAsset(uri, contentType, extension = null,encoding=null)
}

These endpoints are great when actively developing your application. They allow you to grab a file and process it on the fly without waiting for a watcher to reload.

Production

In a compiled production environment, it is not recommended that files get resolved on the fly and processed like this. It adds a large amount of overhead to your application. To solve this, the Asset Pipeline provides an AssetCompiler. This is a configurable compiler that can scan your assets, process them, fingerprint them, and throw them into a target. The target can vary depending on the implementation of the framework in question. For example, in Grails we compile assets into the target/assets folder then copy those into the War file during war build. We then register a Servlet Filter that looks in this folder based on a url mapping to serve assets, check for gzip, set cache headers, and more.

def compiler = new AssetCompiler()

compiler.compile()

This extraction is not yet 100% complete and is in active development. If you are interested in implementing the asset-pipeline for a jvm framework. Feel free to take a look to get an idea what you will need to do.

CDN Notes (Last-Modified Header)

Some CDN providers rely on the existence of a Last-Modified header to successfully use the If-None-Match request header. This will be served up in production mode for assets served locally from asset-pipeline.

Dependencies

To accomodate varying uses of the groovy module (i.e. groovy-all vs. groovy) This library depends on groovy even though it does not directly export it. Make sure you add the following dependenices

dependencies {
  compile 'org.codehaus.groovy:groovy:2.0.7'
  compile 'org.codehaus.groovy:groovy-templates:2.0.7'
  //or
  //compile 'org.codehaus.groovy:groovy-all:2.0.7'
}

Documentation

For Grails 3 asset-pipeline has to be provided both for Grails and Gradle. An example configuration could be:

// Add the Gradle plugin to the build dependencies and apply it to the build process
buildscript {
    dependencies {        
        classpath 'com.bertramlabs.plugins:asset-pipeline-gradle:2.10.1'
    }
}
apply plugin: 'asset-pipeline'

// The plugin could also be applied with the newer syntax 
// plugins {
//     id "com.bertramlabs.asset-pipeline" version "2.10.1"
// }

dependencies {        
    // Add the Grails Plugin to the runtime dependencies
    runtime 'com.bertramlabs.plugins:asset-pipeline-grails:2.10.1'

    // Define needed asset-pipeline plugins with the special assets-scope 
    assets 'com.bertramlabs.plugins:less-asset-pipeline:2.10.1'
    assets 'com.bertramlabs.plugins:sass-asset-pipeline:2.10.1'
}

Contributions

All contributions are of course welcome as this is an ACTIVE project. Any help with regards to reviewing platform compatibility, adding more tests, and general cleanup is most welcome. Thanks to several people for suggestions throughout development. Notably: Brian Wheeler (@bdwheeler), Rick Jensen (@cdeszaq), Bobby Warner (@bobbywarner), Ted Naleid (@tednaleid), Craig Burke (@craigburke1) and more to follow I'm sure...

When creating custom binary plugins to extend this (details also in the grails documentation) You will want to use groovy but not directly export it from gradle. Here is an example of how to do that.

configurations {
    provided
}

sourceSets {
    main {
        compileClasspath += configurations.provided
    }
}

dependencies {
  provided 'org.codehaus.groovy:groovy-all:2.0.7'
  compile "com.bertramlabs.plugins:asset-pipeline-core:2.10.1"
}

Additional Resources