A practical guide to building React applications with Neo4j's GraphQL API.
If you're curious about graph databases:
You've probably heard about graph databases but haven't had the time to build with one. You're uncertain if it will help with your use case or not.
This project gives you hands-on examples using a movie graph database. You'll see how relationships work in practice and why certain queries are just easier with a graph. No theoretical explanations—just working code showing what graphs are good at.
If you already use Neo4j:
You know your way around Cypher and graph modeling, but want to see how to actually build a web app with Neo4j's GraphQL API. This shows you the full stack—React components, mutations, relationship management, all the patterns you need.
The code uses modern tools (React Query, TypeScript, Tailwind) and handles the graph-specific stuff like connect/disconnect operations properly.
A movie catalog where you can:
- Add/edit/delete movies
- Connect actors and directors to movies
- Search across movie titles, taglines, and people
- See how relationships work in a UI
It's the classic Neo4j movies dataset, but surfaced with a web application. Simple enough to understand quickly and yet complete enough to see real patterns.
📚 New to Neo4j GraphQL? → Start with the Tutorial
The TUTORIAL.md is a comprehensive, 8-chapter guide that builds the application step-by-step. Each chapter introduces new concepts progressively:
- Set up your environment
- Read data from Neo4j
- Create new data
- Update existing data
- Delete data
- Manage relationships
- Search and filter
- Deploy your application
Perfect if you want to understand why things work the way they do, with detailed explanations of GraphQL concepts, graph database patterns, and React best practices.
⚡ Already familiar? → Use the Quick Start
The QUICKSTART.md is a condensed reference with all the code you need. It assumes you know React, GraphQL, and basic graph concepts. You can copy-paste components and get running fast.
Perfect if you just need working code and want to customize it for your own project.
- You're comfortable with React, TypeScript, and GraphQL basics
- Node.js 18 or newer
- A Neo4j Aura instance (free tier works)
- React 18 + TypeScript + Vite
- graphql-request (lighter than other GraphQL clients)
- TanStack Query for data fetching
- Tailwind CSS
- Neo4j Aura with DataAPI GraphQL
git clone https://github.com/YOUR_USERNAME/data-api-quickstart.git
cd data-api-quickstart
npm install
# Add your Neo4j DataAPI GraphQL credentials
cp .env.example .env
# Edit .env with your endpoint and token
npm run devOpen http://localhost:5173 and you're ready to go.
- TUTORIAL.md - Complete 8-chapter tutorial (recommended for learning)
- QUICKSTART.md - Condensed reference guide (for experienced devs)
- GETTING_STARTED.md - Environment setup and Neo4j configuration
- BEST_PRACTICES.md - Production patterns and optimization
- TROUBLESHOOTING.md - Common issues and solutions
- ADVANCED_EXAMPLES.md - Pagination, optimistic updates, etc.
- TAILWIND_GUIDE.md - Styling with Tailwind utilities
- SCHEMA.md - Understanding the GraphQL schema
- INDEX.md - Complete documentation index
src/
├── components/ # React components
│ ├── MovieList.tsx
│ ├── MovieForm.tsx
│ ├── Search.tsx
│ └── RelationshipManager.tsx
├── graphql/ # All queries and mutations
│ └── operations.ts
├── lib/ # GraphQL client setup
│ └── graphql-client.ts
├── types/ # TypeScript types
│ └── movie.ts
└── App.tsx # Main app
Pretty standard React setup. The interesting bits are in graphql/operations.ts where you can see how Neo4j relationship queries work.
Here's a concrete example. To find "movies with actors who also acted in movies directed by someone who directed another movie I've seen"—that's a SQL statement with multiple JOINs and possibly multiple queries.
With a graph, it's just following relationships. The query basically describes what you want in plain language:
query {
movies(where: {
actors_SOME: {
actedInMovies_SOME: {
directors_SOME: {
directedMovies_SOME: {
title_IN: $myWatchedMovies
}
}
}
}
}) {
title
}
}Either that's useful for your use case or it isn't, but at least you'll know.
Not every app needs a graph database. But if your data is highly connected—social networks, recommendations, org charts, fraud detection, supply chains, bill of materials—it's worth trying.
- GraphQL fundamentals - Queries, mutations, fragments, and variables
- Graph relationships - Connect/disconnect operations, traversing relationships
- React patterns - Component structure, hooks, state management
- Data fetching - React Query integration, caching, optimistic updates
- TypeScript - Type-safe GraphQL operations
- Production deployment - Building and deploying to Vercel/Netlify
The completed application demonstrates:
CRUD Operations:
// Create
createMovies(input: [{ title: "Inception", released: 2010 }])
// Read
movies(where: { title: "Inception" })
// Update
updateMovies(where: { title: "Inception" }, update: { released: 2010 })
// Delete
deleteMovies(where: { title: "Inception" })Relationship Management:
// Connect actor to movie
updateMovies(
where: { title: "Inception" }
connect: { actors: { where: { node: { name: "Leonardo DiCaprio" }}}}
)
// Disconnect
updateMovies(
where: { title: "Inception" }
disconnect: { actors: { where: { node: { name: "Leonardo DiCaprio" }}}}
)Complex Search:
// Search across movies, actors, directors
movies(where: {
OR: [
{ title_CONTAINS: "matrix" }
{ actors_SOME: { name_CONTAINS: "keanu" }}
{ directors_SOME: { name_CONTAINS: "wachowski" }}
]
})Found an issue? PRs welcome. See CONTRIBUTING.md.
MIT
Ready to start?
- New to Neo4j GraphQL? → Start with TUTORIAL.md
- Need quick reference? → Jump to QUICKSTART.md