Quick Start Guide

Install

Before you begin, you'll want to make sure you have the latest version of node.js installed. We recommend using the Node Version Manager (NVM) instead of installing node.js independently, as you'll be able to easily manage which version of node.js to use for any project.

Once you have node.js installed, you can easily install Anvil at the command line using the Node Package Manager (NPM) which comes with node.js.

 npm install anvil.js -g

Once Anvil installs completely you can verify that Anvil has been installed successfully:

 anvil -v
 #.#.# <-- you should see some numbers which represent the Anvil version installed

If you get an error, please proceed to the Troubleshooting guide.

Install An Extension

Anvil installs extensions to itself from NPM. Let's install a scaffold package to use for this quick start:

anvil install anvil.demo.scaffolds

You should see the NPM output and then a message that the package was successfully installed. To verify, get a list of scaffolds (you should see the three demo scaffolds somewhere in the list):

 anvil scaffolds
 Installed scaffolds:
 . . . 
 demoProject
 demoModule
 demoSpec
 . . .

Congratulations! You've just installed an extension to Anvil that contained scaffolds.

Create A New Project

Let's use the freshly installed demo scaffolds to get a really contrived project started!

anvil new demoProject

You'll be prompted to name your project, pick a license and then choose whether or not you want to generate a package file (hint: do this). Make up a cool project name! (I chose anviltastic) Now cd to your new project folder and explore the structure a bit:

cd anviltastic
ls

You'll see the following directories and files:

|-lib
|-src
|-.gitignore
|-.npmignore
|-build.json
|-header.js
|-LICENSE-*
|-package.json
|-README.md

Sadly, there is nothing to build yet, so let's fix that…

anvil new demoModule
module name? NewThing

Answer the friendly prompts and behold the result of your labor!

|-lib
|-src
 |-newthing.js
|-.gitignore
|-.npmignore
|-build.json
|-header.js
|-LICENSE-*
|-package.json
|-README.md

If you were to cat the guts of the file, you'd see:

module.exports = function() {
 var NewThing = function() {

 };
 return new NewThing();
}

Nothing fancy going on here, but it's something to start with.

Build!

Since our project is setup according to Anvil conventions, we can simply type:

anvil

and get a build. Verify that the build completed successfully by listing the contents of the lib folder. Spoiler alert: it will have your node module's source with a header at the beginning.

Getting a simple build is great, but a bit boring, let's get some tests going.

Installing A Test Framework

For this demo, I'm using Mocha and Should. Let's install those from NPM:

npm install mocha -g <-- if you already have it, you can skip this
npm install should

Now that we have our prerequisites, let's create a spec file from our demo scaffolds:

anvil new demoSpec
name of module being tested? NewThing

Answer the prompts and then check the contents of your spec folder:

|-lib
|-src
 |-newthing.js
|-spec
 |-newthing.spec.js
|-.gitignore
|-build.json
|-header.js
|-LICENSE-*
|-package.json
|-README.md

If you look at the contents, you'll see this:

require( "should" );
var NewThing = require("../src/newThing");

describe( "Define a specification", function() {
 it( "should do something awesome", function() {
  true.should.be.ok;
 } );
} );

Testem Integration

Anvil pre-installs the testem extension (anvil.testem) to itself to assist with running tests across multiple targets. Testem doesn't have out of the box Mocha support, however, so we'll need to define a launcher in our build.json file. Open the build.json file in your favorite editor and note that the scaffold for the demoSpec has added "anvil.testem" property:

{
 "anvil.testem": {
  "launchers": {
   "Mocha": {
    "command": "mocha spec/*.spec.js -- reporter spec"
   }
  },
  "launch": "Mocha"
 }
}

This defines a process-based launcher for testem that tells testem how to run mocha for us.

Testing and CI

Anvil has a CI mode where it will build (and test) continuously triggered by files changes. All builds triggered by file changes should only rebuild files affected by the change. CI mode is enabled with the --ci flag.

To run testem as part of the build, include a --testem flag. This will launch testem's multi-tab interface in the command line which you can navigate with arrow keys (mouse controls don't work with this).

Let's launch both together in our project:

 anvil --ci --testem

You should see one test complete successfully. If you open your project in your favorite editor check to see what happens when you:

Build Cool Stuff!

You've just built a new project with Anvil. At this point you can start using Anvil in your own projects.