neo4j-graphql-skill

When to Use

• Creating a GraphQL API from a Neo4j graph schema with @neo4j/graphql
• Writing type definitions with @relationship, @cypher, @authorization directives
• Using OGM for server-side programmatic Neo4j access (bypasses GraphQL auth)
• Configuring auto-generated queries, mutations, subscriptions
• Securing types/fields with JWT or JWKS-based @authorization rules
• Migrating from v5/v6 to v7 (breaking changes below)

When NOT to Use

• Raw Cypher queries outside GraphQL resolvers → neo4j-cypher-skill
• Spring Data Neo4j / Java entity mapping → neo4j-spring-data-skill
• Generic GraphQL without Neo4j — outside scope

---

Version Matrix

Version	Status	Notes
v7	Current — use ≥ 7.6.0	@node required; options removed; explicit eq syntax
v5	LTS — use ≥ 5.12.15	Older syntax; options: {limit, offset, sort} still valid

Default to v7 unless codebase is on v5.

Security patches — upgrade before shipping auth:

Fix	Fixed in
Subscriptions accepted an unverified JWT from WebSocket connectionParams (auth/authz bypass)	7.5.6 / 5.12.14
Field-level @authentication on a root custom-resolver field ignored when the operation type also had type-level @authentication (privilege escalation)	7.6.0 / 5.12.15

---

Step 1 — Install

npm install @neo4j/graphql neo4j-driver graphql @apollo/server

For subscriptions (CDC required):

npm install ws graphql-ws express body-parser cors

---

Step 2 — Minimal Server Setup

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { Neo4jGraphQL } from '@neo4j/graphql';
import neo4j from 'neo4j-driver';

const typeDefs = `#graphql
  type Movie @node {
    id: ID! @id
    title: String!
    actors: [Person!]! @relationship(type: "ACTED_IN", direction: IN)
  }

  type Person @node {
    id: ID! @id
    name: String!
    movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT)
  }
`;

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

const neoSchema = new Neo4jGraphQL({ typeDefs, driver });

// assertIndexesAndConstraints syncs @id → UNIQUE constraints; wrap in try/catch
await neoSchema.assertIndexesAndConstraints({ options: { create: true } });

const server = new ApolloServer({ schema: await neoSchema.getSchema() });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => ({ token: req.headers.authorization }),
  listen: { port: 4000 },
});