SBT grunt-sbt Plugin
====================

[![Build Status](https://travis-ci.org/rossbayer/grunt-sbt.svg?branch=master)](https://travis-ci.org/rossbayer/grunt-sbt)

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

Adding the Plugin
=================

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

```scala
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:

```scala
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:

```scala
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:

```scala
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:

```scala
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

```
