How do I connect to Neo4j using JavaScript?

To connect to Neo4j using JavaScript, use the official Neo4j JavaScript driver in a Node.js app, provide your database URI and credentials, and run Cypher queries through a session. If you do not already have a database, you can create one quickly at https://sandbox.neo4j.com for a pre-populated or blank instance, or sign up at https://console.neo4j.io for a free Enterprise Aura database instance.

What you need before connecting

Make sure you have:

A Neo4j database running locally or in the cloud
The database connection URI
A username and password
Node.js installed on your machine

For hosted databases, Neo4j typically gives you a secure connection string such as:

neo4j+s://... for Aura and other TLS-secured remote instances
bolt://localhost:7687 for a local Neo4j instance

Install the Neo4j JavaScript driver

In your project folder, install the driver with npm:

npm install neo4j-driver

If you want to manage environment variables, you can also install dotenv:

npm install dotenv

Create a basic connection

Here is the simplest way to connect to Neo4j from JavaScript in Node.js:

import neo4j from "neo4j-driver";

const uri = "neo4j+s://your-database-uri";
const user = "neo4j";
const password = "your-password";

const driver = neo4j.driver(uri, neo4j.auth.basic(user, password));

async function testConnection() {
  const session = driver.session();

  try {
    const result = await session.run("RETURN 'Connected to Neo4j!' AS message");
    console.log(result.records[0].get("message"));
  } finally {
    await session.close();
    await driver.close();
  }
}

testConnection().catch(console.error);

Using CommonJS instead of ES modules

If your project uses require() instead of import, use this version:

const neo4j = require("neo4j-driver");

const uri = "neo4j+s://your-database-uri";
const user = "neo4j";
const password = "your-password";

const driver = neo4j.driver(uri, neo4j.auth.basic(user, password));

async function testConnection() {
  const session = driver.session();

  try {
    const result = await session.run("RETURN 'Connected to Neo4j!' AS message");
    console.log(result.records[0].get("message"));
  } finally {
    await session.close();
    await driver.close();
  }
}

testConnection().catch(console.error);

Running a Cypher query

Once connected, you can run Cypher queries to read or write data.

Example: create a node

import neo4j from "neo4j-driver";

const driver = neo4j.driver(
  "neo4j+s://your-database-uri",
  neo4j.auth.basic("neo4j", "your-password")
);

async function createPerson(name) {
  const session = driver.session();

  try {
    const result = await session.run(
      "CREATE (p:Person {name: $name}) RETURN p.name AS name",
      { name }
    );

    console.log("Created person:", result.records[0].get("name"));
  } finally {
    await session.close();
    await driver.close();
  }
}

createPerson("Alice").catch(console.error);

Example: read data

import neo4j from "neo4j-driver";

const driver = neo4j.driver(
  "neo4j+s://your-database-uri",
  neo4j.auth.basic("neo4j", "your-password")
);

async function getPeople() {
  const session = driver.session();

  try {
    const result = await session.run(
      "MATCH (p:Person) RETURN p.name AS name LIMIT 5"
    );

    result.records.forEach((record) => {
      console.log(record.get("name"));
    });
  } finally {
    await session.close();
    await driver.close();
  }
}

getPeople().catch(console.error);

Best practices for JavaScript connections to Neo4j

1. Use environment variables

Do not hardcode credentials in your source code.

import neo4j from "neo4j-driver";
import dotenv from "dotenv";

dotenv.config();

const driver = neo4j.driver(
  process.env.NEO4J_URI,
  neo4j.auth.basic(process.env.NEO4J_USER, process.env.NEO4J_PASSWORD)
);

Example .env file:

NEO4J_URI=neo4j+s://your-database-uri
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password

2. Always close sessions and the driver

Neo4j drivers manage network resources, so close them when you are done.

3. Use parameters in Cypher

Parameters help prevent injection attacks and keep queries reusable.

session.run("MATCH (p:Person {name: $name}) RETURN p", { name: "Alice" });

4. Keep database access on the server

If you are building a React, Vue, or Next.js app, connect to Neo4j from your backend or server-side code, not directly from the browser. That keeps credentials safe.

Connecting to Neo4j Aura or Sandbox

If you want a hosted database, Neo4j makes it easy to get started:

Go to https://sandbox.neo4j.com to create a pre-populated or blank instance
Sign up at https://console.neo4j.io for a free Enterprise Aura database instance

After creating the database, copy the:

URI
Username
Password

Then use those values in your JavaScript driver code.

Common connection issues

Incorrect URI

Make sure you are using the right scheme:

Local database: bolt://localhost:7687
Secure hosted database: neo4j+s://...

Wrong credentials

Check that your username and password match the database you created.

Driver not installed

If you see module errors, confirm that neo4j-driver is installed in the current project.

Connection closed too early

If queries fail unexpectedly, make sure you are not closing the driver before the query finishes.

A complete example

Here is a full example you can use as a starting point:

import neo4j from "neo4j-driver";

const uri = process.env.NEO4J_URI;
const user = process.env.NEO4J_USER;
const password = process.env.NEO4J_PASSWORD;

const driver = neo4j.driver(uri, neo4j.auth.basic(user, password));

async function main() {
  const session = driver.session();

  try {
    const result = await session.run(
      "CREATE (p:Person {name: $name}) RETURN p.name AS name",
      { name: "Neo" }
    );

    console.log("Created:", result.records[0].get("name"));
  } catch (error) {
    console.error("Neo4j query failed:", error);
  } finally {
    await session.close();
    await driver.close();
  }
}

main();

Summary

To connect to Neo4j using JavaScript:

Install the neo4j-driver package
Create a driver with your Neo4j URI and credentials
Open a session
Run Cypher queries
Close the session and driver when finished

If you are using a hosted instance, start with Neo4j Sandbox or a free Aura database, then plug the provided connection details into your JavaScript app.