Graph App Development Documentation

Neo4j Graph Platform Desktop
1

It was clear from speaking to you all that we should be focussing more effort in documentation and examples around building Graph Apps. In the past week I've published our new Developer Guide for Graph Apps under Neo4j Developer Guides | Neo4j Graph Database Platform.

The aim of this documentation is to be a one-stop shop with all information required to build a Graph App from scratch, regardless of framework.

I'd love to hear your feedback; anything from typos to structural changes. Is the documentation easy to understand and follow? What information do you feel is missing?

Feel free to reply here or get in touch with me directly.

1 Like
2

This documentation is a massive improvement over what I was aware of before. So huge kudos and thank you, boy I wish this had existed when I started halin. I do have some feedback, some is about documentation, and some is about the APIs you're documenting.

API Stuff

This bit of code:

const graphs = context.projects
  .map(project => ({
    graphs: project.graphs.filter(graph => graph.status === "ACTIVE" || graph.connection.type === "REMOTE")
  }))
  .reduce((acc, { graphs }) => acc.concat(graphs), [])

const { url, username, password } = graphs[0].connection.configuration.protocols.bolt

Is pointing to a really obvious missing API endpoint. This is a common thing that most graph apps will have to do (hence why it's in the doc). They shouldn't be doing this, they should instead do context.getActiveGraphs() and context.getActiveProjects() so that everybody isn't pasting the same boilerplate into their graphapps.

If you ever have more code that like 2 lines to do something before you're processing a result, chances are we're missing something in the Desktop API

Please be a bit more opinionated for easy startup times

  • What Neo4j driver version should people use? What scheme should they use to connect? These things are complex on their own, and a basic recommendation to go with a broadly useful general case will save a lot of people time.
  • What frontend should people use? It's fine to be agnostic and say they'll all work, but maybe we should suggest react because it has excellent starter tutorials and code bases of other graphapps to crib off of.
  • GraphQL vs. injected API -- oh my. I'm lazy and haven't done the tradeoff. Which one should I use if I just want to get started ASAP? How would I decide between the two?

Various Nits

  • In Table 2. Table manifest.json Contents -- please explain "homepage", this bit is important and inadequately understood by authors. Please also explain how this is different from homepage in package.json, this was a big source of pain for me as an app author.
  • Deployment via npm and "npm publish". What's the lazy quickest way to set up this repo stuff if I'm any random person? Neo4j people can publish to the Neo4j repo. Should I sign up at npmjs, or what?
  • Deep linking -- why would I want to do that? Could I link to a particular route? I.e. neo4j://fancy-graphapp/state1?foo=bar
  • Plugin dependencies -- great APOC example. What others are valid? It's not going to work if I try to depend on "com.myorg.procedure/customcode", probably because Desktop has never heard of it. Or would that work?
  • Check/request permissions, files, and activation keys: you're using the "injectable API style". I'm assuming that these things can't be done via the GraphQL API. Am I right or wrong?
1 Like
3

I agree that the code is quite verbose. A problem that we have with this is that the window.neo4jDesktopApi has been deprecated by the Desktop team and will be replaced in version 2.0 by the GraphQL API. There's a question there about whether or not we fight to keep the API and build on it with this and other useful methods. Or, maybe this should be something that another dependency/ component kit should take care of.