What is XEOLint?

XEOLint is an ESLint-like tool built specifically for Generative Engine Optimization (GEO) and SEO.

As search evolves toward LLM-driven engines (like ChatGPT Search, Perplexity, and AI Overviews), structural clarity and machine-readability are more important than ever. XEOLint statically analyzes your Next.js project (supporting both the app/ and pages/ routers) to ensure your content is perfectly structured for both traditional crawlers and modern AI agents.

⚡ The V1 Philosophy

• "ESLint for Discoverability": Useful, deterministic, and narrowly focused.
• Audit-First: Finds the missing metadata, broken hierarchies, and crawlability issues.
• Safe Autofixing: Modifies your code only when the fix is deterministic and extremely low-risk (e.g., generating missing robots.txt or sitemap.xml).
• Deep Next.js Support: Natively understands export const metadata, "use client" directives, and <Head> tags.

🚀 Installation

XEOLint is distributed as a Python CLI tool.

pip install xeolint

(Note: XEOLint requires Python 3.9+)

🛠️ Usage

Navigate to the root of your Next.js project and run:

Audit (default — block format)

xeolint audit .

Output:

ERROR  missing_title
  File: src/pages/Terms.tsx
  Message: No <title> found inside <Head> on this page route.
  Fix: Inject a <title> element inside the Next.js <Head> component.

WARNING  missing_canonical
  File: src/pages/Terms.tsx
  Message: No canonical URL defined for this page.
  Fix: Add <link rel='canonical' href='...'> in <Head>.

✅ Passed: missing_robots_txt, missing_sitemap, missing_h1, ...

Summary: 5 errors · 9 warnings · 6 info · 12 passed

Audit (table format)

xeolint audit . --table

Fix

The fix command automatically generates missing files or metadata blocks when it is 100% safe to do so.

xeolint fix .

📐 The 20 Rules

🟢 Safe Auto-Fixes

These rules are automatically fixed when you run xeolint fix.

🔴 Errors (audit only)

🟡 Warnings (audit only)

🔵 Info (audit only)

🤝 Contributing

Local Development

1. Clone the repository.
2. Initialize the environment:

   python -m venv .venv
   source .venv/bin/activate
   pip install -e .
   pip install pytest
   

3. Run the test suite:

   pytest
   

Built to help your code be understood by machines.