/grunt-maven-plugin

Grunt + Maven integration done right

Primary LanguageJavaOtherNOASSERTION

grunt-maven-plugin

grunt-maven-plugin plugin allows you to integrate Grunt tasks into the Maven build process. Grunt is the JavaScript task runner utility. grunt-maven-plugin works on both Windows and *nix systems.

grunt-maven-plugin comes with unique Maven+Grunt Integrated Workflow which removes all impediments present when trying to build project using two different build tools.

Version 1.2.0 introduces new set of tasks for Maven+Grunt Integrated Workflow. If you were using earlier versions, please consult migration guide before upgrading.

Prerequisites

The only required dependency is nodejs with npm. Globally installed grunt-cli is optional and preferred, but not necessary, as installing custom node modules can be problematic in some environments (ex. CI servers). Additional configuration is needed when using local grunt-cli.

grunt-maven-plugin can also run bower install from bower to install front-end dependencies.

grunt-maven-plugin is compatible with JDK 6+ and Maven 3+.

Motivation

grunt-maven-plugin came to life because I needed a good tool to integrate Maven and Grunt. By good i mean not just firing off a grunt process, but a tool that would respect rules from both backend (Maven) and frontend (Grunt) worlds. No node_modules in Maven sources, no Maven src/main/webapp/.. paths in Gruntfile.js.

grunt-maven-plugin allows you to create a usual NPM/Grunt project that could be built and understood by any Node developer, and put it somewhere inside Maven project. It can be extracted at any time and nothing should break. On the other side backend developers don't need to worry about pesky node_modules wandering around src/ - all dependencies, generated sources and deliverables live in dedicated target-grunt directory, doing this part of build the Maven way.

Usage

Add grunt-maven-plugin to application build process in your pom.xml:

<plugin>
    <groupId>pl.allegro</groupId>
    <artifactId>grunt-maven-plugin</artifactId>
    <version>1.2.2</version>
    <configuration>
        <!-- relative to src/main/webapp/, default: static -->
        <jsSourceDirectory>path_to_js_project</jsSourceDirectory>

        <!-- example options usage to get verbose output in logs -->
        <gruntOptions>
            <gruntOption>--verbose</gruntOption>
        </gruntOptions>

        <!-- example options usage to filter variables in given resource -->
        <filteredResources>
            <filteredResource>maven-properties.json</filteredResource>
        </filteredResources>

    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>create-resources</goal>
                <goal>npm</goal>
                <!-- or npm-offline if npm failure is not an option -->
                <goal>bower</goal>
                <goal>grunt</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Usage with local grunt-cli

In order to use local grunt-cli, add

<gruntExecutable>node_modules/grunt-cli/bin/grunt</gruntExecutable>
<runGruntWithNode>true</runGruntWithNode>

options to plugin configuration and add grunt-cli to JS project package.json:

{
    "devDependencies": {
        "grunt-cli": "~0.1.6",
        "grunt": "~0.4.2"
        /*...*/
    }
}

Using NPM in offline mode

NPM downtimes can be painful for (some) development and (all) release builds. grunt-maven-plugin contains npm-offline goal that uses tar-ed node_modules instead of running npm install during each build.

npm-offline flow:

  • extract node_modules.tar in target-grunt
  • run npm-install --ignore-scripts in case there are any dependencies to download that were not tar-ed
  • run npm rebuild

If node_modules dir already exists in target-grunt, it is not overriden. Offline flow is based on this blogpost.

Why only tar, not gz?

  • GIT uses compression internally anyway
  • TAR is lightweight and easy to extract
  • TAR is easier to diff

If there are some compelling arguments for compressing this archive, please post an issue and we might add support in future releases.

Preparing node_modules.tar

In target-grunt:

rm -rf node_modules/
npm install --ignore-scripts
tar cf node_modules.tar node_modules/
mv node_modules.tar ../src/main/webapp/static/

Using linked node_modules

This option is for compatibility reasons, see npm-offline goal for new offline capabilities.

When you want to use tool like frontend-maven-plugin to install node and npm locally or when you have commited-in node_modules directory (or see npm shrinkwrap to freeze module versions), you can make grunt-maven-plugin use preinstalled node_modules. Just replace npm goal with link-node-modules and add nodeModulesPath to configuration options. Example:

    <configuration>
        <nodeModulesPath>${basedir}/preinstalled_modules_dir/</nodeModulesPath>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>create-resources</goal>
                <goal>link-node-modules</goal>
                <goal>grunt</goal>
            </goals>
        </execution>
    </executions>

Under the hood it uses maven-junction-plugin to create a link between provided path and gruntBuildDirectory. Grunt thinks it has its modules in place and executes flawlessly.

Working example

Sandbox project contains simple usage example. It is used to PoC/develop/test new features, so it always stays up to date with SNAPSHOT version.

How it works?

  1. JavaScript project sources from

     sourceDirectory/jsSourceDirectory (default: src/main/webapp/static)

    are copied to

     gruntBuildDirectory (default: target-grunt)

    Copied directory has to contain package.json and Gruntfile.js files

  2. npm install is called, fetching all dependencies

  3. grunt is run to complete the build process

Because the plugin creates its own target dir, it should be added to ignored resources in SCM configuration (like .gitignore).

grunt-maven-plugin options

Plugin options available in <configuration>...</configuration> are:

misc

  • showColors : should Grunt and npm use color output; defaults to false
  • filteredResources : list of files (or expressions) that will be filtered using maven-resources-plugin when creating resources, remember to exclude those files from integrated workflow config, as else Grunt will override filtered values

environment

  • gruntBuildDirectory : path to Grunt build directory (target for Grunt); defaults to ${basedir}/target-grunt
  • sourceDirectory : path to directory containing source JavaScript project directory; defaults to ${basedir}/src/main/webapp
  • jsSourceDirectory : name of directory relative to sourceDirectory, which contents are going to be copied to jsTargetDirectory; defaults to static

node

  • nodeExecutable : name of globally available node executable; defaults to node
  • npmExecutable : name of globally available npm executable; defaults to npm
  • nodeModulesPath : path where preinstalled node_modules are stored

offline

  • npmOfflineModulesFile : name of tar-ed node_modules file; defaults to node_modules.tar
  • npmOfflineModulesFilePath : path to node_modules file, relative to project basedir; defaults to sourceDirectory/jsSourceDirectory

bower

  • bowerExecutable : name of globally available bower executable; defaults to bower

grunt

  • target : name of Grunt target to run (defaults to null, default Grunt target is run)
  • gruntOptions : list of custom options passed to grunt (defaults to empty)
  • ignoreTasksErrors : ignore failing Grunt tasks errors and finish Maven build with success (ignoring 3 and 6 exit code, more on Grunt exit codes)
  • ignoreAllErrors : ignore all Grunt errors and finish Maven build with success (ignoring all exit codes, more on Grunt exit codes)
  • gruntExecutable : name of grunt executable; defaults to grunt
  • runGruntWithNode : if Grunt executable is a js script, it needs to be run using node, ex: node path/to/grunt; defaults to false

Execution goals

  • create-resources : copies all files and filteredResources from sourceDirectory/jsSourceDirectory to gruntBuildDirectory
  • npm : executes npm install in target directory
  • npm-offline : reuses packed node modules instead of fetching them from npm
  • bower : executes bower install in target directory
  • grunt : executes Grunt in target directory
  • clean : deletes gruntBuildDirectory

Maven+Grunt Integrated workflow

Using grunt-maven-plugin is convenient, but there is still a huge gap between frontend and backend development workflow. Various IDEs (Netbeans, IntelliJ Idea, Eclipse) try to ease webapp development by synchronizing changes made in src/webapp/ to exploded WAR directory in target/. This naive approach works as long as there is no need to minify JavaScript sources, compile less files or project does not follow "single WAR" rule and can afford using Maven profiles. Rebuilding project each time a change was made in *.js is a horrible thing. Fortunately grunt-maven-plugin is a great tool to solve this problem.

Idea is to ignore IDE mechanisms and run Grunt build each time a change in static files was made. Traditional workflow looks like:

  1. user changes src/webapp/static/hello.js
  2. IDE detects change
  3. IDE copies hello.js to target/war_name/static/hello.js

This gives little room to integrate other processes in between. Workflow utilizing grunt-maven-plugin:

  1. run Grunt watch process
  2. user changes src/webapp/static/hello.js
  3. Grunt detects changes, copies hello.js to target-grunt/hello.js
  4. run Grunt tasks, produce target-grunt/dist/hello.min.js with source map target-grunt/dist/hello.map.js
  5. Grunt copies results to target/warname/static

Now what happens inside target-grunt is for us to decide, it can be virtually anything - minification, less compilation, running JS tests, JS linting. Anything Grunt can do, just like during heavy build process.

Configuring Maven

Since we want grunt-maven-plugin to take control of what ends up in WAR, we need to tell Maven WAR plugin to ignore our statics dir when creating WAR:

<build>
    <plugins>
	<plugin>
	    <artifactId>maven-war-plugin</artifactId>
	    <version>2.3</version>
	    <configuration>
		<warSourceExcludes>jsSourceDirectory/**</warSourceExcludes>
	    </configuration>
	</plugin>
    </plugins>
</build>

Configuring Grunt

grunt-maven-plugin has a dedicated NPM Grunt multitasks that make integrated workflow work.

grunt.initConfig({
  mavenPrepare: {
    options: {
      resources: ['**']
    },
    prepare: {}
  },

  mavenDist: {
    options: {
      warName: 'war',
      deliverables: ['**', '!non-deliverable.js'],
      gruntDistDir: 'dist'
    },
    dist: {}
  },

  gruntMavenProperties: grunt.file.readJSON('grunt-maven.json'),

  watch: {
    maven: {
      files: ['<%= gruntMavenProperties.filesToWatch %>'],
      tasks: 'default'
    }
  }
});


grunt.loadNpmTasks('grunt-maven');

grunt.registerTask('default', ['mavenPrepare', 'jshint', 'karma', 'less', 'uglify', 'mavenDist']);

For more information please consult documentation of grunt-maven-npm project.

Deep customization of workflow

It is possible to override inner workflow configuration during runtime. Inner properties are extracted from pom.xml and used internally inside workflow Grunt tasks. They reside in target-grunt/grunt-maven.json. After reading inner properties JSON file, workflow task seeks for grunt-maven-custom.json file in target-grunt and overrides original properties with custom ones.

Configuring IDE

Depending on IDE, synchronization processes behave differently. Having JSP files synchronized is a nice feature, so it is up to you to decide what should be turned off. In Netbeans and IntelliJ no configuration is needed, they play nicely with new workflow.

You still have to remember to run Grunt watch process in background so it can monitor changes. It can be run from IDE via grunt-maven-plugin. Define custom runner that will run:

mvn grunt:grunt -Dtarget=watch

You should see process output each time static sources change.

Configuring Eclipse

Eclipse is a special case. Unfortunately it does not read WAR from Maven target, instead it keeps own file hierarchy. Eclipse developers on the team should use deep workflow customization to override properties used by others. Proposed way is to create grunt-maven-custom.json in Maven sources and add it to .gitignore, so it will not pollute source repository. Since i have little experience with Eclipse, i would welcome a contribution of sample configuration, but most probably it is enough to override targetPath property.

Changelog

  • 1.2.2 (31.03.2014)
    • support for npm offline mode
  • 1.2.1 (25.02.2014)
    • executing bower install
  • 1.2.0 (07.02.2014)
    • new Maven+Grunt NPM multitasks
  • 1.1.4 (05.02.2014)
    • added option to ignore Grunt task errors (failing tests etc) (#22)
  • 1.1.3 (25.01.2014)
    • fixed issue with using custom Grunt target and CLI options together (#20)
  • 1.1.2 (06.01.2014)
    • fixed compatibility issue of 1.1.x branch - once again compatible with JDK 6+
  • 1.1.1 (31.12.2013)
    • fixed bug with filtering all resources instead of only chosen
    • fixed bug with Windows paths in workflow properties
  • 1.1.0 (30.12.2013)
    • integrated workflow as a separate, auto-configured Grunt task
  • 1.0.4 (8.12.2013)
    • explicit declaration of resources filtered on create-resources goal
  • 1.0.3 (24.11.2013)
    • passing custom options to grunt executable
    • ability to use external or preinstalled node_modules
  • 1.0.2 (15.10.2013)
    • option to disable npm and grunt color output, by default no colors are shown as it looks bad in Maven logs
  • 1.0.1 (13.09.2013)
    • compatibility with Maven 3.1.x

License

grunt-maven-plugin is published under Apache License 2.0.