Build your first Neo4j Desktop Graph App in vanilla Javascript

25 July 2019 · 6 min read

Neo4j Desktop, part of the Neo4j Graph Platform, is a client application that installs on your desktop OS. It lets you get started quickly by downloading and installing the enterprise edition, and supported plugins. You can group related graphs and applications under a Project. You can also build single-page web applications that run within Neo4j Desktop and have access to these services provided by Neo4j Desktop. There are a number of apps available at https://install.graphapp.io/

In this blog post, we will build a very simple graph app using vanilla javascript.

All code in this blog post is available at https://github.com/aldrinm/simple-graph-app and https://github.com/aldrinm/simple-graph-app-npm

Hello, Graph 🌍️!

Start with simple ‘Hello World’

$ mkdir simple-graph-app

$ cd simple-graph-app

$ touch index.html

Add content to index.html

<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <title>A Simple Graph App</title>
</head>
<body>
   <div id="main">Hello Graph 🌍️ !</div>
</body>
</html>

If you open this file in a web browser, it will look something like this, Hello World

Let’s get this into the Neo4j Desktop,

Go to the Settings > Developer Tools section in the desktop.
Check the Enable development mode
Enter the complete file URL path to our index.html in Development App Entry Point. For exampls, `file:///home/aldrin/simple-graph-app/index.html
Enter a / in Development App Root Path

Developer tools setup

This will enable a new app called Development App in the app panel. Clicking the app will run our page within the desktop.

Running app and the developer tools window

Note the App Developer Tools button at the top. This provides access to the familiar browser Developer tools and can be used to test and debug the app.

Context, Projects, Graphs 📂

Neo4j Desktop exposes the context of all graphs, projects and configurations to apps (you can limit these with permissions, see https://github.com/neo4j-apps/graph-app-starter#requesting-permissions). This context is available through a new desktop api, window.neo4jDesktopApi, injected into the standard window javascript object. Projects are a container for related graphs and applications.

Using the window.neo4jDesktopApi, let’s print to the console, all the projects and graphs available in the desktop environment.

Add the following script block to the index.html file,

<script>
   if (window.neo4jDesktopApi) {
       neo4jDesktopApi.getContext()
           .then((context) => {
               for (let project of context.projects) {
                   console.log("Project :: " + project.name);
                   for (let graph of project.graphs) {
                       console.log("  " + graph.name + " (" + graph.description + ")");
                   }
               }
           }
       );
   }
</script>

getContext returns a promise. Context contains projects which in turn contain graphs. Each graph object contains a name and description (and a number of other properties and methods)

(See https://github.com/aldrinm/simple-graph-app for sample code that prints on the page instead of the console)

Connect to and query the active graph 🏃‍

There can only be one active graph at a time. By default, the app has access to this graph. To connect to the active graph, include the official Neo4j driver at https://www.npmjs.com/package/neo4j-driver

Include the unpkg CDN or jsdelivr CDN,

<script src="https://unpkg.com/neo4j-driver"></script>

This lets us create a driver and then a session, using connect parameters from the active graph instance

...
for (let graph of project.graphs) {
   if (graph.status === 'ACTIVE') {
       //obtain the bolt protocol which has all the connection details
       let boltProtocol = graph.connection.configuration.protocols.bolt;
      
       let driver = neo4j.v1.driver(boltProtocol.url, neo4j.v1.auth.basic(boltProtocol.username, boltProtocol.password));

       //Create a session and execute a query
       let session = driver.session();
       console.log("Labels::");
       session.run("CALL db.labels() YIELD label RETURN label ORDER BY label")
           .then(result => {
               if (result.records && result.records.length>0) {
                   for (var i = 0; i < result.records.length; i++) {
                       const r = result.records[i]
                       console.log(" " + r.get('label'));   
                   }
               }
           })
           .catch(function(error) {
               console.log(error);
           });
   }   
}

Console output

(See https://github.com/aldrinm/simple-graph-app for sample code that prints on the page instead of the console)

And that’s it 🎉- A basic html single page app that runs in the Neo4j Desktop, connects to the active database, executes a query and returns the results!

You can stop right there and use your app just for yourself. But what if you want to share it with your team or the world ? There are a couple of ways to distribute your app. They are described below.

Distribution 🚚

All graph apps require to be packaged into an npm package for distribution.

Install npm and execute the following

$ npm init

Accept or modify the default prompts, except entry point which should be set to index.html

entry point: (index.js) index.html

This creates a package.json file with all the configuration. You can update it at any time.

Next, create a dist folder and copy all the app assets into that folder, including the package.json file. This folder has to be named dist as per the npm package standards. Let’s create a script in the package.json to do this. Update the package.json and add a build task to the scripts section,

...
"scripts": {
   "test": "echo \"Error: no test specified\" && exit 1",
   "build": "rm -r dist || true && mkdir dist && cp *.* dist"
 },
...

then,

$ npm run build

$ npm pack

This generates a file with extension tgz. You can drag and drop this file on the Install Graph Application section of the desktop to install.

Install app dialog prompt

Icons 💎️✨️🍦️

You can customize the icon displayed by specifying one in package.json

...
 "icons": [
   {
     "src": "iconfinder_ladybug.svg",
     "type": "svg"
   }
 ],
...

All icon files have to be specified relative to the location of the package.json and should be packaged into dist

Apps panel showing app icons

Desktop API version 💯️

Finally, you can specify the desktop version supported by your app, in package.json

...
"neo4jDesktop" : {
   "apiVersion" : "^1.2.0"
 }
...

Self updating apps 🏭️

One problem with the above distribution method is that every time you release a new version, all users will have to manually update their installs. If you wish to support and update your app automatically, there is another way - Publish your app to an npm repository and let users install from there. Whenever you release and publish a new version, it will be automatically updated by desktop when it starts up.

Read up about npm-publish

Create an account at npm and let’s publish our app to npm

$ npm login

$ npm publish

If all goes well and your app is published successfully, you can access the meta data of your package at https://registry.npmjs.org/[your-package-name], for instance https://registry.npmjs.org/a-simple-graph-app Use this url to install your app,

Install graph application from npm