Building a Single Page Application with AngularJS and Neo4J – Setup

This is a cross-post from the digitalian

Setting up the environment

In this section I will list all the steps that I had to go through to get my Mac ready for coding with the stack I picked. Hopefully this will be a useful timesaver for anyone who decided to do the same. If you found this page first, you won’t have to do any research. Just follow my footsteps and within minutes (not including the hefty download of Apple’s Xcode) you will be up and running, ready for action :)

Setting up Localhost

I still use OS X 10.7 (Lion), therefore this might not be applicable to your environment if you are using a newer version of OS X. First, I deleted the ~/Sites folder inside my personal folder, then I created a linked folder with the same name pointing to the /Library/WebServer/Documents folder using the following command from Terminal:

sudo ln -s ~/Sites /Library/WebServer/Documents

This way, when you type http://localhost in your browser window, it will point to the content of your ~/Sites folder.

Installing Developer Tools for Mac

You will need to install Developer Tools for Mac which you are installed as part of Xcode. Xcode is available for free – quite a huge download, but you’ll need it.

Installing Homebrew

In order to setup the entire stack we are going to use, you would have to install several packages manually, a very tedious work that I much rather skip. Alternatively, all you need to do is to install Homebrew, a very useful package manager for OS X. To install Homebrew, simply copy and paste the following line in your Terminal window:

ruby -e "$(curl -fsSL"

Homebrew installs packages to their own directory and then symlinks their files into /usr/local.

Installing Node.js

Once Homebrew is installed you can go ahead and install Node.js

brew install node

Easy, right? Next, let’s verify that Node.js is working properly. Inside your ~/Sites folder, create a hello-node.js file and copy the following content in it:

var http = require('http');
http.createServer(function (req, res) {
    res.writeHead(200, {'Content-Type': 'text/plain'});
    res.end('Hello Node.js\n');
}).listen(8124, "");
console.log('Server running at');

Next, run this code from the command line with:

cd ~/Sites
node hello-node.js

You should see the following message in the Terminal window:

Server running at

Next, navigate to in your browser, you should see the message “Hello Node.js”.

Installing npm

npm is Node’s package manager. It is now installed automatically with Node.js so there is no need to do a separate installation.

Installing Express.js

With Node.js and npm already installed, including Express in a web application is just a matter of indicating the dependency on Express within your application package.json file.

Within your application folder (i.e. ~/Sites/HelloWorld), create a file named package.json as follows:

    "name": "hello-world",
    "description": "hello world test app",
    "version": "0.0.1",
    "private": true,
    "dependencies": {
        "express": "3.x"

Now that you have your application dependencies defined, use npm to install them all:

npm install

Once npm finishes, you’ll have a localized Express 3.x dependency in the ./node_modules directory. You may verify this with

npm ls 

which will display a tree with all the application dependencies, in this case just Express and its own dependencies.

To test Express.js I suggest going through the exercise explained here in the Getting Started section, all the way at the beginning of the guide.

Installing Neo4J

Using Homebrew, to install the latest stable version of Neo4j Server, issue the following command

brew install neo4j

Once the installation has completed, you can start Neo4J from the command line with:

neo4j start

This will get a Neo4j instance running on http://localhost:7474. Simply navigate to that URL with your browser to access the database browser utility, which includes some tutorials as well:

Neo4J Broswer

Application Organization

When building a Single Page Application with AngularJS, we are going to be building essentially two pieces:

  • The client, with all the JavaScript, HTML, CSS and various asset files needed for the front-end side of the application to run on the client machine’s browser.
  • The server, with all the JavaScript files required to run the web server on top of Express/Node.js, which will serve the client application requests (GETs, POSTs, PUTs, etc.), connecting the client to the Neo4J persistence layer.

While developing, your machine will play both the client and the server roles, with:

  • the web server running locally on localhost at a specified port (traditionally at port 3000),
  • the database running locally on localhost at port 7474
  • the client application running locally on localhost at port 80

After having read many articles, blog posts and questions on Stackoverflow on how to organize all these files, let me show you the structure that I have adopted, inspired by and by

At the top level, I subdivided the application into its two main components, client and server. I have also added a client-tests folder which I had planned to use for unit testing. Shame on me, I haven’t really used it. Maybe next time around :(

Inside the client folder I structured the application as follows (folders in bold, files in italic):

  • client
    • assets
      • images
    • scripts
      • controllers
      • directives
      • filters
      • services
      • vendor
      • app.js
    • styles
    • views
    • index.html

On the server side of the application, this is the internal folder structure (folders in bold, files in italic):

  • server
    • node_modules (created by npm)
    • routes
    • package.json
    • server.js

In the end, there is no right way to do this. Everyone has their way, some like to group files by type (all controllers together, all directives together, etc.), some like to group them by functionality. There are pro and cons to both approaches, so feel free to pick the one that makes more sense to you. You will always be able to move things around later, if you find yourself limited by your structure.


You are all set, ready for action! I hope you have found this post useful. It took me a while to gather all the information I needed to get to this point. I hope that this summary will help you save some time and be able to get to the fun part sooner :)

Some Optional Goodies

If, like me, you decided to use Sublime Text (either version 2 or 3), if you haven’t done so yet, you might want to install Sublime Package Control. The installation is simple and takes just a few seconds. Go to the installation page and copy the correct script for your version of Sublime Text in the Sublime Text console.

Once that’s installed, simply open the Command Palette (cmd+shift+p),
select “Install Package” and then select “Cypher”. This will install Sublime Cypher, syntax highlighting for Neo4j’s Cypher query language in Sublime Text. You will want to name your cypher files with the .cql extension so that the syntax highlighter will recognize them.

Within Sublime Text’s Package Installer you will also be able to find the AngularJS package, which you may want to install as well.

Neo4J Newbie Tip: How to reset your database

If you are like me, especially during your learning phase of development with Neo4J, you will find yourself building some basic graphs “by hand” as starting point and then running cypher queries that will, sooner or later, mess up your graph.

At that point you have two options:

  1. manually fix the parts of the graph that were affected to go back to a good state to continue development
  2. reset your database to an initial well known state

I have done #1 and got bored pretty quickly with that. Finally I figured out the best way to do #2.

First, write a .cql script which builds the “well known state” that you want to be able to go back to. It might me just a few nodes and relationships or a much more complex structure. Whatever it is, the entire script should look a bit like the following:

START n = node(*) 
MATCH n-[r]-() 
DELETE n, r 
(Neo:Crew { name:'Neo' }),
(Morpheus:Crew { name: 'Morpheus' }),
(Trinity:Crew { name: 'Trinity' }),
(Cypher:Crew:Matrix { name: 'Cypher' }),
(Smith:Matrix { name: 'Agent Smith' }),
(Architect:Matrix { name:'The Architect' }),

The first few lines of the script kill all nodes and relationships from the database. Next comes the long CREATE command, which rebuilds the “well known state” that needs to be recovered.

The only caveat with doing this is that the database will still be the same. This means, for example, that node IDs will keep increasing every time you re-run the above script. If you want to really reset your database, just switch to the Terminal and run the following before you run the cypher script above:

cd /usr/local/Cellar/neo4j/2.0.0/libexec/data
neo4j stop
rm -rf graph.db/
neo4j start

This will stop the database server, completely remove the data folder it relies on, and then restart the server, which will reinitialize itself and create a new data folder with the same name at the same exact location.


I believe that having these “reset scripts” handy will become very useful when you find yourself working on multiple projects at the same time. Sure you could have multiple Neo4J servers running on your machine, one for every project you work on, but I feel that after a while it might become unfeasible to do so. So when you switch project development all you have to do is remove your DB data folder as shown above, and then run your project cypher reset script.

Building a Single Page Application with AngularJS and Neo4J – Introduction

This is a cross-post from the digitalian

Lucky Coincidences

A series of lucky coincidences has recently brought me to dip my toes into a JavaScript-centric programming world completely new to me, from top to bottom. Or maybe I should better say, from front to back:

Front End

  • Using AngularJS, an open-source JavaScript framework, maintained by Google, that assists with running single-page applications.

Back End

  • Using Javascript also on the server side, with ExpressJS, a web application framework built on top of Node.js
  • Using JSON (JavaScript Object Notation) to transmit data objects between the client, the server and the database
  • Using Neo4J, a fully transactional Java persistence engine that stores data structured in graphs rather than in tables.

Initially I had picked the MEAN stack, a full-stack JavaScript development environment very trendy amongst prototypers in the Angular community (where MEAN is an acronym standing for MongoDB, ExpressJS, AngularJS and Node.js).

However, after I had already built a very simple prototype of my SPA (Single Page Application) using the MEAN stack, another lucky coincidence exposed me to Neo4J and it was love at first sight. My decision was that, if I had to learn something new, I would have rather enjoyed being forced into a completely new way of thinking from a data perspective as well, and so I dropped MongoDB in favor of Neo4J from my personal stack.*

“Abandon all hope, ye who enter here.”

In Dante Alighieri’s “Divine Commedy”, when Dante passes through the gate of Hell, the gate bears an inscription which reads “Abandon all hope, ye who enter here.”

It might sound a bit too dramatic to quote that inscription here but, being used to work in a very Microsoft-centric programming environment (Windows, ASP.NET and SQL Server), diving into a Javascript-centric environment felt a lot more challenging than I could have ever imagined. I had to abandon at the entrance of this new world most of what I was used to, most of what I knew and all the tools I was already familiar with. As much as it was frightening, though, finding myself almost completely disoriented felt also refreshingly good.

In this series of posts I will try to put down in words both the mental process I went through and some of the technical challenges that I found myself facing and had to overcome while building a ficticious personal project, which consists of building a Single Page Application (SPA) recreating some/most of Trello‘s functionality.

New Tools for the Trade

Being that this is a personal project and since it doesn’t require using any Microsoft technology, I decided to work off of my MacBook Pro. This decision meant that, among other things, I had to find either a decent text editor or an IDE to write my code, as well as an easy way to version control my files.

After trying out a few different tools, I opted for Sublime Text, a very versatile cross-platform text and source code editor which I liked from the beginning.

To manage the source code I decided to grab the opportunity to try out Git, a free and open source distributed version control system designed and developed by Linus Torvalds in 2005. I downloaded it and installed it on my Mac and connected it to my empty GitHub account.

Next, I created my first repo (i.e. repository) and, in order to better understand the inner workings of Git, I decided to just use the OS X Terminal, issuing git commands directly from the command line. Needless to say, not being a command line type of person, I grew tired of that within a couple of weeks, especially because I found the add/commit/push sequence a bit too cumbersome/annoying (even with some of the shortcuts that git offers). So, recently, I have downloaded GitHub for Mac. So far so good, although it’s a bit too early to really say how I feel about it. I do enjoy the fact that with one click I am finally able to commit all my changes and sync them to my GitHub repo.

A side effect of working with GitHub was the rediscovery of the Markdown language, a minimal markup language used for all README files in GitHub. Being a plain text formatting syntax, no special editor is needed to write content using Markdown, although there are some specially-designed editors which preview markdown files with styles. For now I picked Mou a very nice markdown editor which provides instant preview side-by-side to the text being edited.

Mou Editor

Coincidentally, just a few weeks ago, finally, WordPress has announced that they are now supporting GitHub’s version of Markdown within the blog post editor! Perfect timing for me to really get addicted to this simple writing tool! Because Markdown is simple enough to learn in a few minutes, clean and elegant enough to be readable no matter your context, and it is becoming the defacto markup language of the Internet, at least among the slightly geekier types who do know markup languages :)

Perfect timing! Markdown on WordPress!

this is an image

Awesome! Just when I was getting more into the swing of things (got the image?) using Markdown, between writing .md files on GitHub and using IA Writer on my Mac, WordPress has announced that we can finally use a fancy version of Markdown (which includes also code formatting and code highlighting, just like the GitHub version) also on WordPress hosted blogs!

Now, if only iPads had a Markdown friendly keyboard!1

  1. I know, I know, some applications do use the new features provided by iOS7 and do extend the default keyboard, but really the default keyboard should be a bit more Markdown friendly and at least provide easy access to symbols like #,*,@ and tabs