A GEO and SEO linter and autofixer for Next.js applications
Project description
🔍 XEOLint
A fast, deterministic GEO and SEO linter & autofixer for Next.js
Philosophy • Installation • Usage • Rules
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.txtorsitemap.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.
| Rule | What it checks |
|---|---|
missing_robots_txt |
robots.txt or app/robots.ts exists |
missing_sitemap |
sitemap.xml or app/sitemap.ts exists |
🔴 Errors (audit only)
| Rule | What it checks |
|---|---|
missing_title |
<title> or metadata.title is defined |
missing_h1 |
Page has an <h1> tag |
🟡 Warnings (audit only)
| Rule | What it checks |
|---|---|
missing_meta_description |
description is defined in metadata |
missing_canonical |
Canonical URL is defined |
missing_open_graph |
openGraph object in metadata |
missing_twitter_card |
twitter object in metadata |
page_noindex_risk |
Accidental noindex directives |
client_only_critical_content |
Heavy text hidden behind "use client" |
multiple_h1 |
More than one <h1> on a page |
weak_heading_hierarchy |
Heading levels are skipped (e.g. h1 → h3) |
missing_semantic_landmarks |
Missing <main>, <nav>, <footer> |
missing_alt_text |
Images missing meaningful alt text |
missing_json_ld |
No JSON-LD structured data found |
client_only_content_risk |
Multi-signal detection of heavy client-side rendering risk |
🔵 Info (audit only)
| Rule | What it checks |
|---|---|
unclear_page_purpose |
H1/hero text is too vague for GEO |
weak_entity_clarity |
Brand/product name missing from key areas |
missing_faq_or_structured_qa |
No FAQ section or FAQ schema |
orphan_risk_internal_linking |
Pages with no internal links pointing to them |
generic_anchor_text |
"Click here" / "Learn more" style links |
🤝 Contributing
Local Development
- Clone the repository.
- Initialize the environment:
python -m venv .venv source .venv/bin/activate pip install -e . pip install pytest
- Run the test suite:
pytest
Built to help your code be understood by machines.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file xeolint-0.1.0.tar.gz.
File metadata
- Download URL: xeolint-0.1.0.tar.gz
- Upload date:
- Size: 16.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f326765cf957e937190cc79661327400effdb1a22fbfa45b30d913e9e7696c9e
|
|
| MD5 |
1750aa642d8c03e5030e3673ddd9ff0b
|
|
| BLAKE2b-256 |
1b56d1807b780a67f679c074c4dc46a2cd6d5763df20dd5b36d5e40cedfe7120
|
File details
Details for the file xeolint-0.1.0-py3-none-any.whl.
File metadata
- Download URL: xeolint-0.1.0-py3-none-any.whl
- Upload date:
- Size: 32.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ec8e104757f7e89ef62b8d38bafac07f726c004c0083b46359d60ca2b16e5a98
|
|
| MD5 |
8ef3b60d319fa8cec8042b87804bd7ad
|
|
| BLAKE2b-256 |
cdde74d2c8054c9071f62f7f1b899267da32ccc1acdee43348830ace009d462c
|
