I Built a Free Cypher Query Formatter for Neo4j — Here's Why and How

If you've worked with Neo4j for any length of time, you've probably stared at a wall of unformatted Cypher that looks something like this:

MATCH (p:Person {name: 'Alice'})-[:FRIENDS_WITH]->(friend:Person)-[:WORKS_AT]->(c:Company) WHERE friend.age > 25 AND c.name STARTS WITH 'Neo' WITH p, friend, c, count(*) AS cnt ORDER BY cnt DESC LIMIT 10 OPTIONAL MATCH (friend)-[:LIVES_IN]->(city:City) WHERE city.population > 100000 RETURN p.name AS person, collect(DISTINCT friend.name) AS friends, c.name AS company, city.name AS city ORDER BY person ASC

Not exactly readable. I kept copy-pasting queries from logs, Slack messages, and Stack Overflow answers that looked like this — and manually reformatting them was eating into my time. So I built a tool to fix it.

---

What I Built

Cypher Query Formatter — a free, browser-based tool that takes a messy Cypher query and formats it instantly with proper indentation, line breaks, and syntax highlighting.

The same query from above becomes:

MATCH (p:Person {name: 'Alice'})-[:FRIENDS_WITH]->(friend:Person)-[:WORKS_AT]->(c:Company)
WHERE friend.age > 25
    AND c.name STARTS WITH 'Neo'
WITH p, friend, c, count(*) AS cnt
ORDER BY cnt DESC
LIMIT 10
OPTIONAL MATCH (friend)-[:LIVES_IN]->(city:City)
WHERE city.population > 100000
RETURN p.name AS person,
    collect(DISTINCT friend.name) AS friends,
    c.name AS company,
    city.name AS city
ORDER BY person ASC

Much better.

---

Features

• Instant formatting — paste your query, click Format (or hit Ctrl+Enter)
• Syntax highlighting — keywords, functions, labels, properties, strings and parameters all highlighted in distinct colors
• Configurable indent — 2 spaces, 4 spaces, or tabs
• Keyword case conversion — UPPERCASE, lowercase, or Capitalize
• Dark and light theme
• Copy to clipboard or download as .cypher file
• 100% client-side — your queries are never sent to any server

---

How It Works — The Technical Side

This was a fun vanilla JS project. Here's the approach I took:

Tokenizer

The core is a hand-written tokenizer that walks the query character by character and emits typed tokens: clause, sub_clause, function, string, number, comment, parameter, operator, bracket, etc.

The tricky part was handling multi-word clauses correctly. Cypher has things like OPTIONAL MATCH, ON CREATE SET, ORDER BY, STARTS WITH, and IS NOT NULL. A naive word-by-word approach would break STARTS WITH into the operator STARTS and the major clause WITH — which is wrong.

The solution was to match multi-word sub-clauses before checking major clauses, using a longest-match-first sorted list:

const MULTI_WORD_SUB_CLAUSES_SORTED = [
    'IS NOT NULL',
    'STARTS WITH',
    'ENDS WITH',
    'WITH HEADERS',
    'IS NULL'
];

By checking these first, STARTS WITH is correctly identified as a sub-clause operator before WITH can be matched as a major clause.

Formatter

After tokenization and classification, the formatter rebuilds the query string with:

• A newline before each major clause (MATCH, WHERE, RETURN, etc.)
• An indent + newline before AND, OR, XOR inside WHERE blocks
• An indent + newline after commas in RETURN, WITH, and SET clauses
• Proper spacing around operators and brackets

Syntax Highlighter

The highlighter runs the same tokenizer on the already formatted output and wraps each token type in a <span> with a CSS class. Context matters here — an identifier after a : is a label (red), after a . is a property (blue), otherwise it's a variable (pink).

---

What I Learned

Writing a tokenizer from scratch is surprisingly fun. The edge cases are where it gets interesting — escaped quotes inside strings, backtick-escaped identifiers, block comments, parameters starting with $.

Multi-word keyword matching needs careful ordering. This tripped me up early on and produced some very wrong formatting before I got it right.

Cloudflare Pages is a great free host for static tools like this. Zero config, instant deploys from git, generous free tier.

---

Try It

👉 cypher-formatter.pages.dev

It's free, open to everyone, and works in any modern browser. If you hit a query, it formats incorrectly. I'd genuinely love to hear about it in the comments. Edge cases in Cypher are plentiful, and I'm sure I've missed some.

---

Built with vanilla JavaScript. No frameworks, no dependencies, no server.

---