The js2neo library is a tiny Neo4j connector for JavaScript. It contains the bare minimum required to run Cypher queries in around 2.5KB when gzipped. No support for transactions or routing is provided.

Get a copy...

Download js2neo.min.js
( bytes, bytes gzipped)
Get the code

Alternatively, use the CDN link...

<script src=""></script>



cx =

To connect, call the method with settings for your database. This returns a connection object that wraps a single web socket connection. For example:

var cx ={host: "", user: "technige", password: "P4ssw0rd!"})

The following arguments are supported:

Name Type Description
secure boolean A flag to indicate whether or not to use a secure web socket.
user string The name of the user as which to authenticate.
password string The password for the given user.
host string The host name or IP address of the database server.
port number The port number of the database server.
userAgent string A custom user agent string.

In addition, the following event handlers can be specified:

Name Signature Description
onOpen function(metadata) Called when a web socket connection is successfully established. The event passes connection metadata containing secure, user, host, port and userAgent attributes.
onHandshake function(metadata) Called after the handshake that immediately follows a successful connection. This adds a protocolVersion to the connection metadata.
onInit function(metadata) Called with connection metadata on successful initialisation, following the handshake. This is the final stage of setup for a Bolt connection and therefore receipt of this event indicates that the connection is ready to run Cypher queries.
onInitFailure function(failure) Called if initialisation fails, generally due to an authentication error. The event passed represents the failure that occurred and contains code and message attributes. On receipt of this event, the connection can be deemed defunct.
onClose function(event) Called when the underlying web socket is closed, either gracefully or through error. The event is a regular web socket CloseEvent., parameters, eventHandlers)

The run method enqueues a Cypher query to run over the connection. For example:"RETURN $x", {x: "hello, world"}, {onRecord: console.log})

This call accepts a Cypher statement plus optional maps of parameters and event handlers.

The following event handlers are available:

Name Signature Description
onRecord function(values) Called for each record returned in a result. The function is called with an array of values.
onHeader function(metadata) Called on receipt of the result header. The function is called with a map of metadata, including a fields array that contains the record keys.
onFooter function(metadata) Called on receipt of the result footer. The function is called with a map of metadata.
onFailure function(failure) Called if the Cypher execution fails. The failure object passed to the handler contains code and message attributes that describe the nature of the failure.


Closes the connection immediately. To request the connection only closes after the full result has been completely received, add this call into the onFooter handler for the relevant run call. To cater for the eventuality where the run fails, also add this to the onFailure handler.

© 2018, Nigel Small