Graph App Development for Neo4j Desktop

The Injected API is provided through the neo4jDesktopApi object. The getContext() method returns a Promise which in turn resolves to an object containing a projects key. Each Project contains a list of Neo4j Databases and a list of files.

If the context should change for any reason, for example if the active database changes or has been stopped, an event will be fired. You can listen for these changes using the onContextUpdate method on the API which provides an Event object which includes the type of event (for example), the new context and the previous context.

The following events will trigger a context update via the API:

The GraphQL API contains the same information as the injected API, but instead is accessed via a GraphQL library. For this example we will use Apollo Boost. The Apollo Boost package is available via npm or yarn

The information required to access the GraphQL API are provided as part of the URL.

You can then use the Apollo Client to query the GraphQL API endpoint. For example, the following code will give you a list of all projects and their databases.

The next step is to create an instance of the JavaScript driver. This will be the point of interaction with a Neo4j Database. Now that we have the credentials from the previous step, we can run a series of filter and reduce functions to produce a list of graphs that a driver instance can be created for. There will be a maximum of one Active graph in Desktop (with the status ACTIVE), but you may also have remote graphs that could be displayed. To find any active graphs, you could run a reduce and filter on the current context.

Once you have the correct credentials, you can create an instance of the Driver and run the session.

If you use npm or yarn, you will be familiar with the package.json file. This file sits in the root of your project and holds various metadata including the name of your project and any third-party dependencies. Adding a neo4jDesktop setting to your package.json will allow you to tie your Graph App to a particular version of the Neo4j Desktop API or {#permissions}[request certain permissions]. The name and version of the project are read from package.json and used when deciding whether to install a new Graph App or update an existing install.

In this example, we are tying the Graph App to the Neo4j Desktop API version 1.4.0 or higher and requesting permission to access all Graphs created in Neo4j Desktop.

The manifest.json file is read during the installation process to gather additional information to Neo4j Desktop about your Graph App. In a packaged installation of a Graph App (either by manually creating a .tar.gz file or via npm pack), this file should be added to the /dist folder before packaging. For Graph Apps hosted on the internet, the manifest.json file should be served in the same directory as your index.html file.

The following image demonstrates how the values from manifest.json are used by Neo4j Desktop.

Any values provided in manifest.json will override a value provided in package.json. For example, if package.json lists version 1.0.0 but manifest.json specifies 1.2.3, the value 1.2.3 will be used.

At the minimum, your project should consist of a dist/ directory containing an index.html file plus any other JavaScript and CSS files that are required to run the Graph App. The root directory should also include a package.json file and optionally a set of latest release notes in release-notes.md.

The most common option for deploying a Graph App is to create a .tar file. This can be created by running the npm pack command.

If you have created a project with a command line tool (for example create-react-app or @vue/cli) then the build scripts should be configured for you already. If not, you can create a build script in package.json to move the appropriate files to the dist/ folder.

Once the files are in the dist folder, you can run the npm pack to package the graph app into a .tar file.

Any files or directories that you do not want to include in the .tar file can be listed in a .npmignore file. By default, the file will be named using the name and version properties from package.json. The resulting .tar file can be installed either by pasting a URL or dragging the tar file into the Install form at the bottom of the Graph Apps pane in Desktop.

Any published npm package can be installed by copying and pasting the npm registry URL. For example, the Neo4j Cloud Tool Graph App can be installed via Neo4j’s npm registry with the URL https://neo.jfrog.io/neo/api/npm/npm/neo4j-cloud-ui. Neo4j Desktop will periodically check for updates to npm packages and install them automatically.

More information on the npm package command is available on docs.npmjs.com.

A good example of an Online Deployment is Halin. You can install the hosted version of Halin by entering https://halin.graphapp.io into the Install form at the bottom of the Graph Apps pane and clicking the Install button. The hosted version of Halin hosts a manifest.json in the website’s root directory.

You can provide a deep link to your app using the neo4j-desktop:// scheme and the name of your app from package.json. For example, if the name of the app is my-graph-app the link would be the following:

You can pass parameters through to the graph app to help set the initial state of the app. For example, in the URL above, the ?key=value will append a key property with a value of value to the graph app’s url.

The neo4jDesktopApi has an onArgumentsChange function that allows you to listen to changes in the applications arguments, for example when a new deep link has been clicked. On load, and for each subsequent change of parameters, the callback function is called with two arguments; the original string and an object containing the decoded keys and values.

Your graph app can also link to Neo4j Browser using the neo4j-desktop:// scheme and the Graph App name neo4j-browser. Additionally, you can specify a command and argument to automatically run as it loads. For example, if you wanted to run the :play movies command to open the Movies Browser Guide, you could use the following link:

You can also start Neo4j Browser with a pre-populated cypher query by setting cmd in the query string to edit and the arg to the Cypher query in a URL encoded form.

You can link to Bloom by using the neo4j-desktop:// scheme, and the Graph App name neo4j-bloom. You can also add a search parameter as a URL encoded string to auto-fill the search bar when bloom opens.

You can specify any plugins that your Graph App depends on within manifest.json file. Any plugin with a valid coordinate from Maven Central will be will be automatically installed to all local databases within the current active project in Neo4j Desktop.

For example, if your Graph App requires APOC then your manifest.json file may look something like this:

In order to specify your own plugins here, they must be published to Maven Central. Once published, the coordinates of the Maven Artifact can be added to the array.

If a Graph App requires the use of a privileged API (for example executing Java or Node.js), these will need to be specified either in the neo4jDesktop section of package.json or in manifest.json. Permissions can be defined as an array:

Or alternatively, a map-like object can be provided with a short description of how the permission will be used.

Activation Keys can be used to unlock functionality within your Graph App. An Activation Key is a JET token, similar to a JWT token but with specific fields that are used to grant access to protected resources and premium functionality. All users are required to enter an Activation Key when they first download desktop.

All keys are currently issued by Neo4j and are tied to the name from your package.json file. They hold the following keys:

Activation Keys are held as part of the context. If you have requested the activationKeys setting then it may be appropriate to filter the activation keys by their feature name.

If you are interested in using Activation Keys to unlock features in your app, please get in touch and we will see what we can do.

Neo4j Desktop allows you to drag and drop files into a project for later use. For example, you could create a Browser Guide to explain your project to your coworkers or create set of Cypher scripts to seed a new database within the project or to hold commonly run queries. The Neo4j Desktop UI displays a link to these files so they can be quickly opened in Neo4j Browser.

You can also access these from your Graph App. For example, a visualisation app may take a set of cypher queries and display them in a forced graph layout. Each file can be accessed via HTTP through Neo4j Desktop’s API and therefore can be loaded through node’s http module or a third party package like axios.

To get all cypher files from every, you could run a .map and .reduce on Neo4j Desktop’s context:

The use-neo4j library provides hooks for running Cypher queries against a Neo4j Database. The Neo4jProvider component will detect the Neo4j Desktop API and show a list of Projects and Graphs configured in Neo4j Desktop. The library falls back to a generic login form which allows the user to enter their own credentials.

The vue-neo4j plugin provides a wrapper for the JavaScript driver in all Vue.js components via this.$neo4j object. There is also a set of helper functions for developing Graph Apps. For more information, check out the Github repository for using Vue.js with Neo4j.