SBT grunt-sbt Plugin

An sbt plugin for adding Grunt.js to your sbt build.

Adding the Plugin

First, add the plugin to your plugins.sbt file:

addSbtPlugin("org.rbayer" % "grunt-sbt" % "1.0")

If you want to use the latest version of the plugin directly from source control, add the following to your plugins.sbt file:

lazy val root = project.in(file(".")).dependsOn(gruntSbtPlugin)

lazy val gruntSbtPlugin = uri("https://github.com/rossbayer/grunt-sbt.git")

Using the Plugin

By default, the plugin comes with a basic configuration that can be used for typical projects involving Grunt.js. These settings can be referenced in your build.sbt file via the gruntSettings variable, like so:

import org.rbayer.GruntSbtPlugin._
import GruntKeys._

name := "grunt-example"

version := "1.0"

organization := "org.rbayer"

scalaVersion := "2.10.3"

gruntSettings

Without modification, the settings defined in gruntSettings will add a grunt resource generator task that will be invoked as part of the resources task and a test:grunt task that will be invoked as part of the test task. Additionally, a grunt command will be introduced that allows you to call grunt from the sbt console and execute an arbitrary command (for instance, serve).

Tasks

The following tasks are available when gruntSettings is included in your build:

• npmInstall - Executes npm install in your current working directory to install any NPM package dependencies defined in package.json. By default, this will be executed when resources is run. If no package.json file is found in the current project's base directory, this task will simply exit.
• compile:grunt (As a resourceGenerator) - Executes grunt tasks associated with the Compile configuration. By default, the build task will be executed in your Gruntfile during the resources task of Compile.
• test:grunt - Executes grunt tasks associated with the Test configuration. By default, the test task will be executed in your Gruntfile.

Commands

The following commands are provided by the plugin:

• grunt - Command that will execute an arbitrary set of tasks using Grunt.js in your current sbt console session. Example:

  grunt --force jshint serve ...

Settings

To override or modify plugin settings, import GruntKeys and modify keys as appropriate in your build.sbt file:

import org.rbayer.GruntSbtPlugin._
import GruntKeys._

name := "grunt-example"

version := "1.0"

organization := "org.rbayer"

scalaVersion := "2.10.3"

gruntSettings

// Customize grunt plugin settings

gruntPath := "/path/to/grunt-cli/bin/grunt"
    

The following settings are available for the plugin that can be overridden:

Setting	Default Value	Description
gruntPath	"grunt"	The path to the grunt executable. This setting can be used to override the location of Grunt.js when it is not on the $PATH, like in a CI environment.
gruntNodePath	Nil	The path to the node executable. If set, this will cause the plugin to execute the grunt executable specified via gruntPath by passing it as an argument to the node interpreter process (i.e. node /path/to/grunt). The same also applies for npm. Set this only if node is not on the $PATH.
gruntNpmPath	"npm"	The path to the npm executable. This setting can be used to override the location of npm when it is not on the $PATH.
gruntTasks	"build" in Compile or "test" in Test	Sequence of tasks to execute via grunt in a particular configuration. By default, during resources, grunt build will be executed, and grunt test will be executed during a test task.
gruntResourcesDirectory	None	Optional directory containing files generated by the grunt build that should be managed by sbt. If set, any files found in the configured directory will be added to resourcesManaged in sbt.
gruntResourcesClasspath	file("META-INF/resources")	Path where files generated by grunt and stored in the gruntResourcesDirectory will be stored in the JAR/WAR generated by package. This allows you to control what the tree of resources in your final artifact will look like. By default, resources will be copied to META-INF/resources so they are accessible from a Servlet container automatically.
gruntForce	false	Boolean indicating whether the --force argument should be provided to grunt in a particular configuration.

Here are some example customizations to give an idea of how your Grunt build can be integrated into sbt:

import org.rbayer.GruntSbtPlugin._
import GruntKeys._

name := "grunt-example"

version := "1.0"

organization := "org.rbayer"

scalaVersion := "2.10.3"

gruntSettings

// Update grunt to be run from a local npm install for a CI environment

gruntPath := "node_modules/grunt-cli/bin/grunt"

// Change the tasks run during resource generation
// This will invoke `grunt jshint concat uglify`

gruntTasks in Compile := Seq("jshint", "concat", "uglify")

// Change the final classpath of generated resources

gruntResourcesClasspath in Compile := file("META-INF/resources") / name.value / version.value