Skip to main content

Installation

Packages​

npm install mikro-orm-neo4j

neo4j-driver and @neo4j/cypher-builder are dependencies of the package, so they arrive with it. What you supply yourself is MikroORM:

npm install --save-dev @mikro-orm/core @mikro-orm/decorators @mikro-orm/reflection
PackageWhy
@mikro-orm/corePeer dependency, 7.x. Pin it exactly if you use stored routines.
@mikro-orm/decoratorsWhere MikroORM 7 keeps @Entity, @Property and friends. Not needed with defineEntity.
@mikro-orm/reflectionTsMorphMetadataProvider, if you would rather not annotate every property type by hand.
reflect-metadataOnly for the legacy decorator route, imported once at your entry point.
The driver re-exports core

mikro-orm-neo4j re-exports everything from @mikro-orm/core, plus its own MikroORM, EntityManager, EntityRepository and defineConfig. Importing MikroORM from the driver is what selects the Neo4j platform — there is no driver: option to set.

A server to develop against​

Neo4j 5 or newer; 5.7 or newer if you plan to use schemas, which need composite uniqueness constraints.

docker run --rm -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5.25

Add APOC or GDS with -e NEO4J_PLUGINS='["apoc"]' when you want the stored routines they ship. Browse the graph at http://localhost:7474.

For tests, the driver's own suite starts a container per suite with Testcontainers and rolls every write back — see testing.

Connecting​

src/mikro-orm.config.ts
import { defineConfig } from 'mikro-orm-neo4j';

export default defineConfig({
  clientUrl: 'bolt://localhost:7687',
  user: 'neo4j',
  password: 'password',
  dbName: 'neo4j',
  entities: ['./dist/entities'],
  entitiesTs: ['./src/entities'],
});
OptionMeaning
clientUrlBolt URL. bolt://, bolt+s://, neo4j:// (routing) and neo4j+s:// all work.
user, passwordBasic auth.
dbNameThe Neo4j database. neo4j is the default one on a fresh server.
ensureDatabaseSet false when the database already exists and the user may not create one (Community only has neo4j).
replicasRead replicas — see read replicas.
driverOptionsPassed to neo4j-driver, e.g. { fetchSize: 500 }, connection pool sizes, custom trust settings.
debug['query', 'query-params'] and friends — see observability.

Node.js​

Node 22 or newer. The driver reads globSync from node:fs, which older runtimes do not export; on Node 20 the failure is a SyntaxError at import time rather than something informative. See troubleshooting.

Next​