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> 
Let’s get this into the Neo4j Desktop,
- Go to the
Settings > Developer Toolssection 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
/inDevelopment App Root Path
This will enable a new app called Development App in the app panel. Clicking the app will run our page within the desktop.
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); }); } } 
(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.
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
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,
You can optionally add a release-notes.md file to your package. This is displayed to the user whenever the app is updated by desktop.
Now whenever you publish a newer version of your app, it will automatically be updated by desktop, on startup.
Source code for above content is available at https://github.com/aldrinm/simple-graph-app and https://github.com/aldrinm/simple-graph-app-npm
