Cursor Rules Template: Neo4j Cypher Query Builder (Node.js)

Overview

Cursor Rules Configuration for Cursor AI in a Node.js backend using Neo4j Cypher. This Cursor rules template provides a copyable .cursorrules block and stack-specific guidance to ensure safe, parameterized Cypher queries with the official Neo4j JavaScript Driver.

Direct answer: Use these rules to constrain Cursor AI behavior when constructing Cypher queries, enforce best practices, and keep generated code aligned with your Node.js project structure.

When to Use These Cursor Rules

• You are building a Node.js service that communicates with a Neo4j graph database.
• You want all generated Cypher queries to be parameterized and safe against injection.
• You need to enforce a consistent coding style (TypeScript preferred) and a shared driver usage pattern.
• You require explicit authentication and secure handling of database credentials via environment configuration.
• You plan CI/CD integration with linting, unit tests, and integration tests for graph queries.

Copyable .cursorrules Configuration

# Cursor Rules for Neo4j Cypher Query Builder (Node.js)
# Framework Role & Context
ROLE: Backend Engineer using Node.js with Neo4j (Neo4j JavaScript Driver)
CONTEXT: Build and verify Cypher queries via a typed query builder; ensure safety and testability.

# Code Style and Style Guides
STYLE: TypeScript + ESLint (recommended) + Prettier; strict null checks; no dynamic runtime eval.
LANG: en
LINE-ENDING: LF

# Architecture & Directory Rules
DIRECTORY: src/
DB: src/db/driver.ts; neo4j config in src/config/neo4j.ts
MODULES: services/, controllers/, routes/

# Authentication & Security Rules
AUTH: Bearer JWT stored in Authorization header; do not log tokens; use env vars for credentials.
SECURITY: prohibit plaintext Cypher concatenation; always parameterize.

# Database and ORM patterns
DRIVER: Neo4j JavaScript Driver; use driver.session() with read/write access per operation.
PATTERN: use parameterized queries via query builder; avoid string interpolation for user input.

# Testing & Linting Workflows
TEST: npm test (unit/integration); lint: npm run lint; CI runs tests on PRs.

# Prohibited Actions and Anti-patterns for the AI
Do Not: concatenate strings to form Cypher; expose credentials; bypass auth checks; rely on hard-coded queries.
Do: use parameterized queries; use a dedicated Neo4j driver instance; validate input shapes.

Recommended Project Structure

neo4j-node-app/
  src/
    config/
      neo4j.ts
    db/
      driver.ts
    query/
      builder.ts
    services/
      cypherService.ts
    controllers/
      apiController.ts
  tests/
    unit/
      cypherService.test.ts
    integration/
      cypherQuery.integration.test.ts
  .env.example
  package.json
  tsconfig.json

Core Engineering Principles

• Single source of truth for Neo4j connection configuration.
• Parameterize all generated Cypher queries; never interpolate user input.
• Separation of concerns: query construction, execution, and response shaping.
• Immutable, typed data flows from input to Cypher parameters.
• Explicit test coverage for unit and integration scenarios against a test Neo4j instance.
• Cursor AI safety: enforce do-not-do patterns and anti-patterns clearly in prompts.

Code Construction Rules

• Use a dedicated Neo4j driver instance; share across services from a single pool.
• Define a typed Cypher builder API; expose methods like buildMatch, buildCreate, buildRelation.
• Always pass map/params objects for query values; never embed values directly.
• Maintain a clear separation between query templates and runtime parameters.
• Follow TypeScript typing rules; enable strictNullChecks.
• Keep queries readable by formatting and including comments for complex patterns.
• Do not rely on ORM abstractions that hide Cypher concerns (avoid over-abstracting).

Security and Production Rules

• Store credentials in environment variables; never commit secrets.
• Use TLS/SSL for database connections where supported; validate certificate sources.
• Enforce RBAC by routing queries through a service layer with access scopes.
• Audit logging for query execution without exposing sensitive data.
• Limit query timeouts and set transaction budgets to prevent abuse.

Testing Checklist

• Unit tests for the Cypher builder functions with parameterized inputs.
• Integration tests against a local or test Neo4j instance.
• Linting and type checks in CI; ensure TS compilation passes.
• End-to-end tests for API routes that exercise Cypher generation.
• Security tests focusing on input validation and auth flow.

Common Mistakes to Avoid

• Direct string interpolation of user inputs into Cypher.
• Reusing a single global session across concurrent requests without proper handling.
• Forgetting to close sessions or transactions; leaking resources.
• Assuming the builder handles all security concerns without explicit validation.
• Skipping TypeScript types or enabling loose compiler settings.

FAQ

What is the Cursor Rules Template for Neo4j Cypher Query Builder in Node.js?

This template provides concrete Cursor AI instructions to generate safe, parameterized Cypher queries using the Neo4j JavaScript Driver in a Node.js backend. It ships a copyable .cursorrules block and stack-specific guidance for reliable, testable code generation.

Which stack does this template cover?

Node.js with Neo4j, using the official Neo4j JavaScript Driver, a TypeScript codebase, ESLint/Prettier formatting, and a Cursor AI-based code generation workflow.

How do I apply the .cursorrules block in my project?

Copy all lines from the code block into a file named .cursorrules in your project root, then ensure your CI runs lint and tests to validate the rules. Cursor AI will reference this file during code generation.

What are the main security considerations?

Always parameterize all Cypher queries, manage credentials via environment variables, and restrict access to database operations through a service layer. Do not log sensitive values or expose them in prompts.

What testing and linting workflows are recommended?

Run unit tests for query builders, integration tests against a Neo4j test instance, and lint/type checks in CI. Use Jest for tests and ESLint/Prettier for style enforcement.