Ninja Framework Tutorial – PART 1: Setting up Ninja with Netbeans

This a part of a series of tutorials on Ninja Framework. You can click here to see the full set.


For the first part, I will walk you through how to get a Ninja site running with Netbeans. The end product is as simple as just launching Netbeans and hit Run Project. No command line needed. As of this writing these are the current versions of what I’ll be using:

  • JDK 1.7.0_25
  • Apache Maven 3.3.1
  • Ninja Framework 5.1.0
  • Netbeans 8.0.2

Brief Intro

(You can skip this section if you want.)

Lately I’ve been looking into web development with Java. As with general web development, working with simply just raw java is tedious and prone to lead to a ton of bad practices and lots of unnecessary code. Why reinvent the wheel? Having experience with Laravel, I decided using a framework would be a sensible choice. After choosing between Spring MVC and Ninja, I opt for Ninja.

Reasons for my choice is besides the point for this post; chances are if you are here you have already decided to use Ninja over a dozen other Java web development frameworks.

Why write a series of tutorials? The Ninja Framework website is pretty nicely documented, but I feel things could be simpler, and there are some holes that unless you’ve some experience you’re going to be a lost. In addition I don’t see many tutorials written about it. Everybody in YouTube land is doing more Ruby and PHP. When I searched “Ninja framework” in YouTube, all I found is an hour long video. Even in Google search I barely found anything useful.

Let’s Start!

First off, I’m assuming you’re going to start with nothing. I’m using Windows 8.1, but you should be able to apply it to Linux or whatnot. Following this guide, you first install JDK and Maven, followed by Netbeans (If you’re sure which edition, just choose all! XD). JDK and Netbeans is fairly straight forward so I won’t guide you through.

Maven is a little tricky. It’s not like you download some installer and you’re on your way. Netbeans does come with Maven built in, but currently it is using 3.0.6 whereas Ninja requires 3.1.0 and above.

What you have to do, is download the binary zip from the Maven website, extract the contents to your C drive. You will see a folder “apache-maven-3.3.1” or something like that in the root of your C drive. Rename this folder to “mvn” to make things simpler.

Add “C:\mvn\bin” directory to your environment PATHs so you access the “mvn” command in your command prompt. If you see some JAVA_HOME error when typing “mvn -version” in command prompt, add a environment user variable JAVA_HOME pointing to JDK:

2015-04-19 16_49_53-Environment Variables

If you’re not sure how to add an environment PATH or user variable, google it (lol).

Replace Bundled Maven in Netbeans

In Netbeans, go to Tools > Options.

Under “Java”, click the “Maven” tab. In “Maven Home” combobox, choose “C:\mvn”.

2015-04-19 16_54_14-Options

Now comes a catch: It doesn’t work! Netbeans is looking for a “mvn.bat” file in “C:\mvn\bin” which doesn’t exist…

Or does it?

It does, but named “mvn.cmd” for some reason. So the fix is simple: make a copy of “mvn.cmd” and rename it to “mvn.bat”.

Create New Ninja Project in Netbeans

So you saw the guide on how to create your first Ninja application right? This section follows just that. You can use command prompt if you like; I just thought it’s simpler to go through Netbeans.

Select “New Project…” icon in Netbeans. Under Categories, select “Maven”, and under Projects, select “Project from Archetype”. When you click Next, you’ll see a list of “Known Archetypes”. You can filter the result using the search bar, typing “ninja”.

2015-04-19 17_06_21-New Project


Choose “ninja-servlet-archetype-simple”. Lastly give your project a name and you’re finished creating your project!

Then, for first run right click your new Maven project and select “Clean and Build”. Wait a while and it should look like this:

2015-04-19 17_10_50-NetBeans IDE 8.0.2

If your project structure doesn’t look like this, right-click within the Projects window in NetBeans and from the “View Java Packages As” menu, you can now choose “Reduced Tree”. (

SuperDevMode via “Run Project”

SuperDevMode guide in Ninja’s website. For a first few days of using Ninja, I actually open up the command prompt, cd to the ninja project directory and copy paste “mvn ninja:run” every time I want to run SuperDevMode. When I want to terminate SuperDevMode I press “Ctrl-C” and type “y” to cancel batch process.

This is plain silly. Obviously IDEs are made to make this process simpler.

Right click your project and select “Properties”. Under Catergories, select “Actions”. Under Actions, select “Run Project”. Change the contents of “Execute Goals” from “package” to

ninja:run -Dninja.port=8080

2015-04-19 17_22_38-Project Properties - NinjaPlayground


You’ll see a new file called “nbactions.xml” added to your project. If you remove this file, it will revert back to the default “Run Project” settings in Maven.

 Port numbers VS Context Path

Why specify a port number you ask? Ninja Framework uses 8080 by default after all. But say you have multiple Ninja sites and you want yo run them at the same time. Distinguishing them is as simple as using different port numbers. You can then bookmark these in Chrome for convenient access.

But you can also use ContextPath like so, yes?

mvn ninja:run -Dninja.context=/your_context_path

Well, it gets the paths to your site screwed up. When I first did this the site was unable to find its assets (css, js files) because they were linked as such:

<script type="text/javascript" src="/assets/webjars/bootstrap/3.3.2/js/bootstrap.min.js"></script>

If your base URL changed from “localhost:8080” to “local:8080/your_context_path”, it still looks for the assets in “localhost:8080”. Therefore you have to retrieve your assets as such:

<script type="text/javascript" src="${contextPath}/assets/webjars/bootstrap/3.3.2/js/bootstrap.min.js"></script>

This is annoying for me to do, so I prefer to just change port numbers and give meaningful names via URL bookmarks.

 Ignore, I Don’t Want IDE Managed Deployment

Last step! (: Click “Run Project”. You’ll be presented with a dialog as below:

2015-04-19 17_41_45-NinjaPlayground - NetBeans IDE 8.0.2

Select “Ignore, I don’t want IDE managed deployment”, and SuperDevMode will now be running! Note that it won’t launch your browser automatically as other netbeans web projects; you’ll have to launch a browser manually and enter the URL “localhost:8080” (Not a big hassle I hope).

2015-04-19 18_33_34-Edit Post ‹ Bruceoutdoors Blog of Blots — WordPress

To turn off SuperDevMode, go to the Output window and click “Stop the currently executing build”:

2015-04-19 17_43_47-NinjaPlayground - NetBeans IDE 8.0.2


From now on, whenever you press “Run Project” (F6), it will execute SuperDevMode automatically. This will be specific only to this project. What a time saver!

Setup the Debugger

Follow the instructions under Debugging Under Netbeans from the Ninja Framework site:

  1. Right click your Project and open “Project”
  2. Click on “Action” on the left.
  3. Choose “Debug project”
  4. Enter “jetty:run” into the “Execute Goals” input field
  5. Enter “jpda.listen=maven” into the “Set Properties” field

This information will also go to your “nbactions.xml” file, as with how you set up “Project Run”. After that it is the same thing as running: you need to select “Ignore, I don’t want IDE managed deployment”. You’ll have to do this once, but afterwards you can use the dropdown shortcut:

2015-04-19 23_15_43-NinjaPlayground - NetBeans IDE 8.0.2

It will only use port 8080, so if you have SuperDevMode using port 8080 you should turn it off. Technically you can change this port number, but you’ll have to edit “pom.xml” and do configurations… which I despise; it’s not like ninja:run where you can specify it as a parameter. So therefore I will assume you’ll only debug one site at a time.

Technically you can debug one site using port 8080 and have 3 other ninja sites running on SuperDevMode (but using different port numbers) at the same time. Cool yes?

Bonus Section: Automatic Refreshing – Super Auto Refresh 

Workflow at this point is as follows: You make a change in Netbeans, Netbeans auto compiles for you, SuperDevMode picks up and changes and updates itself. You then refresh your browser to see the changes. The last step at this point is still done manually.

F5, F5, F5…

So to top it all up before closing, I wish to recommend another convenience tool called Super Auto Refresh. You can the Chrome extension via this link. Set the tab to your Ninja site for 2 seconds interval refresh and you’ll never have to manually refresh again! Of course, you could lag your PC doing this, so you shouldn’t try this if it slows you down.


That is all for part 1. In part 2 I talk about Adding CSS, Javascript Libraries using WebJars.


One thought on “Ninja Framework Tutorial – PART 1: Setting up Ninja with Netbeans

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s