Building Graph Apps with React (Part 1)

Neo4j Desktop added the capability to build and run your own custom apps, connecting to your Neo4j backend. The Graph Gallery and the Halin monitoring app were already featured here. This post is the first in a series to get you going with Graph App development.

This post has been written by Cristina Escalante from our partners at tsl.io.

Getting started with any new project can be both exciting and frustrating. How do I see a working example of what I want to do? Where do I report bugs? Keeping frequently asked questions in mind, this article will assume you have Neo4j Desktop installed and walk you step-by-step through getting started with Graph App development.

What is a Graph App?

In contrast to the more common web applications that need to be hosted on a server, Neo4j Graph Apps are more similar to plugins for Neo4j Desktop. A Graph App is a single-page web application (written in JavaScript using e.g. Vue, React, Angular) designed to work inside of Neo4j Desktop, which is an Electron-based application that provides an API for discovering and connecting to Neo4j graphs. Although a Graph App may interact with a server, it does not need to be connected to the internet and interact solely with the data available from Neo4j Desktop.

Furthermore, you could take an existing webapp and wrap it into a Graph App, or take a Graph App and promote it to a standalone application.

How do I use an existing Graph App?

Published Graph App

If a Graph App has already been published, installing and running it is relatively painless.

  • Open Neo4j Desktop.
  • Under “Graph Applications” you can see a “Install Graph Application” field
  • Find the Graph Application you wish to install — here’s a list https://github.com/neo4j-apps/awesome-graph-apps
  • Copy the URL of the graph app that interests you
  • Paste into the “Install Graph Application” field and tap the Install button
  • Pick a project and add the application in the top row.

Done!

How do I build my own Graph App?

You can create your own Graph App from scratch or by wrapping an existing single page Neo4j app (or any other “online URL”). The examples apps in the graph-app-starter repository will help get you off the ground.

But really, how would you get started?

Let’s get the Single File Graph Application started. Although merely an index.html file, it is a good introduction of the Neo4j Desktop API.

First, clone the graph-app-starter repository and navigate to graph-app-starter/examples/basic-single-file/, taking note of the path to the root folder.

Open the index.html file in a browser and take note of the file URL. You could also statically serve it locally or from somewhere else.

In Neo4j Desktop:

  • Open Settings on the sidebar
  • Toggle Development Mode: On
  • Copy paste the App’s root path and entry point into the appropriate fields
  • Start the Development App under My Projects
  • Voila!

If you’re familiar with React you should find your way through that Graph App. It uses the

Existing Graph App Repository

If you want to test or modify a Graph App someone else has published, you use the same steps. Below is an example using the open- source Graph App: Graph Examples.

  • Clone the repository and take note of the App’s root path on your disk
  • Run the app using the instructions in the readme (e.g. with yarn start) and note the app entry point
  • Enable Developer Mode and add the root path and entry point
  • Start the Development App under your selected project
  • The Development Mode also shows Developer Tools and Reload buttons with each Graph App which are really handy for problem solving.

What if I find a Problem?

If you find a problem with how Neo4j Desktop and the Graph App you’re working on are trying to interact, create an issue report here or contact the developers of the Graph App you’re trying to use.

Graph Apps published by the Neo4j team would have repositories to report issues here too: https://github.com/neo4j-apps

In the next instalment of the series we will have a closer look at the Neo4j Desktop API and the existing React components in Graph App Kit.