A Javascript library consists of some Javascript files, and potentially some resources like images, templates, and stylesheets. In Maven, these are arranged in the following directory structure:
The one item that might require some explanation is pom.xml. It is a “project object model” file, which has information about your project and its configuration. It'll be explained piece-by-piece below.
my-library/
. pom.xml
. src/
. main/
. javascript/
. resources/
. test/
. javascript/
. resources/
Initial Steps
The first thing you need to do is install Maven. Go to http://maven.apache.org and grab a copy of 2.2.x. Extract it somewhere and add the bin directory to your path.
$ export PATH=$PATH:path/to/maven/bin && mvn --version
If that worked out right, you should see a Maven version and some Java environment information displayed.
Next you need to edit your settings.xml file. Run the following command:
$ mkdir ~/.m2 && gedit ~/.m2/settings.xml
and add this content to the file:
http://gist.github.com/557035#file_settings.xml
These settings are adding the Sonatype OSS repository where the Javascript plugin and several popular libraries that I have packaged for Maven use are hosted.
Creating the Project
All that is needed to create a Javascript library is a POM and some source code. A simple POM looks like this, and is called pom.xml:
http://gist.github.com/557035#file_pom.xml
There are a couple notes about this file, as seen in the comments above.
1. In Maven, every project is defined uniquely by these 4 pieces. groupId should be a subdomain under your control. artifactId is the name of this project. version is typically [major].[minor].[point]-[type]; type is either a “release” or a “snapshot”. This pertains to deployment which I'll cover in the next article.
2. A project has many dependencies and a few possible scopes. In this case we're using the “test” scope. The other important one is “runtime”, which I'll describe later. Each dependency has a version; is good practice to use a range. In this case we can use any 1.4.x version of jQuery. This is especially important as many dependencies are added to the project, which may all rely on different point releases of the same library.
3. Each project can have many plugins. The one that makes JS development possible is the javascript-maven-plugin. Not all plugins require the 'extensions'
Once you have your POM in place, you need to create some Javascript. Create a file called hello.js in src/main/javascript:
http://gist.github.com/557035#file_hello.js
Adding QUnit Tests
Now that we have a little functionality in place, let's create a test for it. Create suite-hello.html in src/test/javascript:
http://gist.github.com/557035#file_suite_hello.js
First, all tests match the pattern suite-*.html. Second, notice your hello.js file is in the scripts/ directory, while external dependencies (qunit and junit) are in scripts/${artifactId}/filename.js. These are conventions I have put in place that mirror web application packaging, which will be covered later.
One thing to notice is that qunit is never declared as a dependency to the project. This is likely to change in the near future. At the moment it is automatically added by the plugin code. It might be safe to declare it explicitly, but I'll leave that as an exercise to the reader.
Now run the following command:
my-library$ mvn test && cat target/surefire-reports/qunit.txt
If everything went right, you should get a message that says “Build Successful” and have a brief summary of the executed test displayed.
Next Time...
In the next article I'll show you how to release your project to an open source repository, and declare where it exists in an SCM for automatic release tagging.
