leangraph

library1.2.2jsnpmunverified

LeanGraph is a lightweight, embeddable graph database with full Cypher query support, powered by SQLite. Current stable version is 1.2.2, released under the MIT license with regular updates. It passes 100% of the openCypher TCK (2,684 scenarios, Neo4j 3.5 baseline), providing Cypher feature parity with Neo4j 3.5. Key differentiators include instant startup, ~50MB memory footprint, no Docker or JVM requirement, offline operation, and simple backup via file copy. Ideal for production graph workloads without infrastructure complexity, offering local, remote, and test modes. TypeScript types are shipped with the package.

database

npm install leangraph

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LEANGRAPH

leangraph

databasejavascriptv1.2.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LeanGraph

✓ import { LeanGraph } from 'leangraph'

✗ const LeanGraph = require('leangraph')

Package is ESM-only; named import required. Default import will not work.

LeanGraphOptions

✓ import type { LeanGraphOptions } from 'leangraph'

✗ import { LeanGraphOptions } from 'leangraph'

Type import only for TypeScript; remove if using plain JavaScript.

LeanGraph (async factory)

✓ const db = await LeanGraph({ project: 'myapp' })

✗ const db = new LeanGraph({ project: 'myapp' })

LeanGraph is a function, not a class. Always await its call.

Demonstrates creating a local LeanGraph database, inserting nodes and a relationship, querying with Cypher, and closing the connection.

import { LeanGraph } from 'leangraph'; async function main() { const db = await LeanGraph({ project: 'myapp' }); // Create nodes and relationship await db.execute(/* cypher */ ` CREATE (alice:User {name: 'Alice'})-[:FOLLOWS]->(bob:User {name: 'Bob'}) `); // Query const users = await db.query('MATCH (u:User) RETURN u.name AS name'); console.log(users); // [{ name: 'Alice' }, { name: 'Bob' }] db.close(); } main().catch(console.error);

Debug

Known issues

gotchaLeanGraph function must be awaited; forgetting await returns a Promise.

fix

Use const db = await LeanGraph(options);

affects: >=1.0.0

gotchaLocal mode requires better-sqlite3 peer dependency; if missing, LeanGraph throws 'better-sqlite3 is not installed'.

fix

Install better-sqlite3 as a dependency (npm install better-sqlite3).

affects: >=1.0.0

gotchaRemote mode requires LEANGRAPH_API_KEY environment variable; without it, queries fail with authentication error.

fix

Set LEANGRAPH_API_KEY=lg_xxx in your environment.

affects: >=1.0.0

gotchaData directory for local mode defaults to './data'; if directory does not exist, database creation fails silently or throws.

fix

Ensure ./data directory exists, or set dataPath option.

affects: >=1.0.0

gotchaWhen using TypeScript, importing LeanGraphOptions as a value instead of type causes runtime error.

fix

Use import type { LeanGraphOptions } from 'leangraph' for type-only imports.

affects: >=1.0.0

Errors

Common errors & fixes

better-sqlite3 is not installed. Please run 'npm install better-sqlite3'.

Missing peer dependency for local or test mode.

fix

npm install better-sqlite3

TypeError: LeanGraph is not a constructor

Calling new LeanGraph() instead of LeanGraph() as a function.

fix

const db = await LeanGraph({ project: 'myapp' });  // no 'new' keyword

Error: ENOENT: no such file or directory, mkdir './data'

Default data directory './data' does not exist.

fix

mkdir -p ./data or set dataPath option to an existing directory.

Uncaught (in promise) Error: Authentication failed. Please provide a valid API key.

Missing or invalid LEANGRAPH_API_KEY in remote mode.

fix

Set LEANGRAPH_API_KEY=lg_xxx environment variable.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

better-sqlite3optionalRequired for local and test modes to manage the embedded SQLite database

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/co-l/leangraph ↗

packageleangraph ↗

homepagehttps://leangraph.io ↗