AgriciDaniel/on-page-seo: Bulk SEO Audits for 500 Pages, 74 Metrics

AgriciDaniel/on-page-seo: Bulk SEO Audits for 500 Pages, 74 Metrics

SEO auditing at scale is a persistent headache for developers and technical marketers. Most tools either lock you into expensive SaaS tiers for bulk crawling or force you to stitch together half a dozen APIs yourself. You end up paying for page limits you don't need, or building brittle internal scripts that break when Google changes Core Web Vitals thresholds again.

AgriciDaniel/on-page-seo addresses this directly. It's an open-source, self-hosted SEO analyzer that crawls up to 500 pages per audit and evaluates 74 distinct SEO metrics per page — including Core Web Vitals, on-page elements, and technical health markers. Built in TypeScript with a React^{↗ Bright Coding Blog} 19 frontend and Express backend, it's designed for teams that want ownership of their audit pipeline without the per-seat pricing of enterprise SEO platforms.

This article breaks down what AgriciDaniel/on-page-seo actually does, how it works under the hood, and how to get it running locally or in production.

What is AgriciDaniel/on-page-seo?

AgriciDaniel/on-page-seo is a full-stack SEO analysis application maintained by Agrici Daniel, an AI Workflow Architect who documents his build process publicly — including a YouTube walkthrough of the journey from an n8n workflow prototype to this complete application. The project sits at the intersection of developer tooling and marketing automation: it's not a library or CLI utility, but a deployable web application with a dashboard, real-time progress tracking, and exportable reports.

With 119 GitHub stars and 42 forks as of its last commit on June 6, 2026, the project has gained modest but genuine traction in the developer community. It's released under the MIT License, making it suitable for commercial modification and redistribution without legal friction.

The tool's architecture reflects modern full-stack conventions. The frontend uses React 19 with TypeScript, Vite for builds, TanStack Router for client-side routing, and TanStack Query for server state management. The backend is Node.js with Express, using SQLite via better-sqlite3 for data persistence — a deliberate choice that keeps deployment simple without requiring a separate database server. External data comes from two paid APIs: Firecrawl for page discovery and DataForSEO for the actual metric analysis.

This stack matters practically. SQLite means you can run the entire application on a single VPS or even a local machine without Docker^{↗ Bright Coding Blog} complexity. The TypeScript-first approach means type safety extends across the frontend, backend, and a shared types package — reducing the class of bugs that typically plague API contract mismatches.

Key Features

Bulk Page Discovery via Firecrawl The tool doesn't require you to manually submit URLs. Firecrawl automatically discovers pages on your target domain, handling the crawling logic that would otherwise require custom spider configuration. This is particularly useful for large sites where sitemap.xml files are incomplete or missing entirely.

74 SEO Metrics Per Page Through the DataForSEO integration, each discovered page gets evaluated across 74 distinct metrics. The README doesn't enumerate all 74 individually, but the coverage includes standard on-page SEO factors (title tags, meta descriptions, header hierarchy, internal linking) alongside Core Web Vitals — specifically LCP (Largest Contentful Paint), FID (First Input Delay), and CLS (Cumulative Layout Shift). These three metrics are Google's officially confirmed ranking signals, making their inclusion non-negotiable for any serious audit tool.

Real-Time Progress Streaming Audits of 500 pages take time. The application uses Server-Sent Events (SSE) via the /api/audits/:id/progress endpoint to push live updates to the frontend. Users watch completion percentages update without polling, which reduces server load and provides immediate visual feedback.

Exportable Reports Results can be downloaded as CSV or JSON, fitting into existing data pipelines or spreadsheet-based workflows. This matters for teams that need to share findings with stakeholders who don't have direct application access.

Dark Mode Full dark mode support via the Tailwind CSS^{↗ Bright Coding Blog} and Shadcn/ui implementation — a small but telling signal that the maintainer cares about developer experience during long audit sessions.

500-Page Audit Ceiling The documented limit of 500 pages per audit is a concrete constraint, not a marketing number. For larger sites, this implies a segmentation strategy: run multiple audits by subdirectory or site section.

Use Cases

Technical SEO Due Diligence for Acquisitions When evaluating a potential acquisition or partnership, developers need rapid technical assessment of a target site's SEO health. AgriciDaniel/on-page-seo provides structured, exportable data across 74 metrics without requiring a subscription to a premium SaaS tool that the target company might also use.

Pre-Launch Quality Assurance Before major site migrations or redesigns, teams can baseline their current SEO performance. The Core Web Vitals tracking specifically helps catch performance regressions that visual testing misses — a 200ms LCP degradation won't show up in screenshot comparisons but will hurt rankings.

Agency Client Reporting For freelancers and small agencies, the tool offers a white-labelable alternative to expensive SEO platforms. The self-hosted nature means client data never passes through third-party analytics servers, addressing GDPR and data sovereignty concerns that increasingly block SaaS adoption in European markets.

Internal Marketing Team Tooling Companies with in-house SEO and engineering teams often build fragmented internal tools. AgriciDaniel/on-page-seo provides a unified, maintainable foundation that engineers can extend — the MIT license permits modification, and the TypeScript codebase is approachable for teams already using React/Node.

Competitive Benchmarking Run identical audit parameters against competitor sites to identify structural SEO gaps. The CSV export enables comparative analysis in Python^{↗ Bright Coding Blog}, R, or spreadsheet tools that marketing analysts already know.

Installation & Setup

The README provides explicit commands that should be reproduced exactly. Here's the complete setup flow with context for each step.

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Firecrawl API key (get one at firecrawl.dev)
• DataForSEO account (register at dataforseo.com)

Step 1: Clone the repository

git clone https://github.com/AgriciDaniel/on-page-seo.git
cd on-page-seo

This pulls the monorepo structure containing client/, server/, shared/, and data/ directories.

Step 2: Install dependencies

# Install all dependencies (root, client, and server)
npm run install:all

The install:all script is a convenience wrapper that runs npm install across the workspace roots. The project uses a monorepo pattern but doesn't appear to use pnpm workspaces or npm workspaces explicitly — the custom script handles cross-directory installation.

Step 3: Configure environment

cp .env.example .env

Edit .env with your API credentials. Notably, the README mentions you can alternatively configure API keys through the application's settings page — useful for teams that prefer runtime configuration over environment files.

Step 4: Start development servers

npm run dev

This concurrently starts:

• Client at http://localhost:3005
• Server at http://localhost:3001

The dual-server development setup is standard for Vite + Express applications. Vite's dev server handles Hot Module Replacement for the React frontend, while Express runs the API independently.

Real Code Examples

The README contains limited explicit code snippets, which is common for application repositories (as opposed to libraries). Below are the documented examples with explanation.

Production Build and Start

# Build both client and server for production
npm run build

This compiles the TypeScript backend and creates a Vite production bundle for the frontend. The output is designed for unified deployment — the production server serves static files and handles API routes on the same port.

# Start production server
NODE_ENV=production npm run start

Setting NODE_ENV=production explicitly is critical: it switches Express into production mode (enabling view caching, disabling verbose error stacks) and ensures the application serves the built client assets from dist/ rather than proxying to the Vite dev server.

Available NPM Scripts

The README documents these commands in table form. Here's the complete set for reference:

# Development commands
npm run dev              # Start both client and server
npm run dev:client       # Start only the client
npm run dev:server       # Start only the server

# Build and production
npm run build            # Build both client and server
npm run start            # Start production server

# Setup
npm run install:all      # Install all dependencies

These scripts are defined in the root package.json and delegate to the appropriate workspace directories. The separation of dev:client and dev:server is useful when debugging backend issues without the frontend build overhead, or when running the frontend against a staging API.

API Endpoint Structure

While not a "code example" in the traditional sense, the documented REST API is worth reproducing for developers integrating with or extending the tool:

POST   /api/audits              # Start a new SEO audit
GET    /api/audits              # List all audits
GET    /api/audits/:id          # Get audit details with results
GET    /api/audits/:id/progress # SSE stream for real-time progress
GET    /api/audits/:id/export   # Export audit as CSV or JSON
DELETE /api/audits/:id          # Delete an audit
GET    /api/settings            # Get API configuration status
PUT    /api/settings            # Update API credentials

The SSE endpoint for progress streaming is particularly notable — it uses a persistent HTTP connection rather than WebSockets, which simplifies infrastructure requirements (no need for Redis or sticky sessions in load-balanced deployments).

Note: The current README documentation focuses on application usage rather than library integration. Developers seeking to embed audit functionality in existing systems would need to examine the source code directly or contribute documentation for programmatic usage.

Advanced Usage & Best Practices

Database Management SQLite via better-sqlite3 stores audit data in the data/ directory. For production deployments, ensure this directory is on persistent storage (not ephemeral container filesystems) and is included in backup routines. The README doesn't specify migration tooling — inspect server/src/db/ for schema management approaches.

API Rate Limiting Both Firecrawl and DataForSEO have usage-based pricing and rate limits. The 500-page audit ceiling likely exists to prevent accidental quota exhaustion. For larger sites, implement subdirectory segmentation and stagger audit starts to respect provider limits.

Security Considerations The settings endpoint (PUT /api/settings) stores API credentials. In production, run the application behind HTTPS, restrict network access to the admin interface, and consider rotating API keys quarterly. The MIT license permits security hardening forks.

Performance Optimization Core Web Vitals data depends on DataForSEO's measurement infrastructure, not the application's own servers. However, the audit processing itself is CPU-bound when parsing 74 metrics × 500 pages. For high-frequency usage, deploy on instances with adequate single-thread performance (better-sqlite3 operates synchronously).

Monitoring The SSE progress endpoint can double as a health check — if audits start but never progress, the Firecrawl or DataForSEO integration may be failing silently. Log audit start/completion events to your existing monitoring stack.

Comparison with Alternatives

AgriciDaniel/on-page-seo occupies a specific niche: developers who want ownership of their audit data and predictable costs (pay only for Firecrawl/DataForSEO usage, not per-seat SaaS pricing). The trade-off is operational responsibility — you maintain the server, handle updates, and manage API credentials.

Screaming Frog remains the established choice for technical SEO professionals who need unlimited crawling without API dependencies. Sitebulb offers superior visualization for client presentations. Ahrefs provides competitive intelligence beyond on-page factors. Choose AgriciDaniel/on-page-seo when data sovereignty and custom integration matter more than out-of-the-box polish.

FAQ

What does the 500-page limit mean in practice? Each individual audit can analyze up to 500 pages. For larger sites, run multiple audits segmented by URL path or subdomain.

Do I need paid subscriptions to use this? Yes — Firecrawl and DataForSEO both require API keys with associated costs. The tool itself is free under MIT License.

Can I run this without Docker? Absolutely. The SQLite backend and Node.js runtime require no containerization. Deploy directly on any VPS or internal server.

Is the data stored securely? Audit data resides in your local SQLite database. You control encryption, access, and retention policies — data never passes through the maintainer's infrastructure.

What React version is required? The frontend uses React 19, which was stable as of the last commit date (June 2026). Ensure your deployment environment supports this version.

Can I modify the 74 metrics? The metric set is determined by DataForSEO's API response. Custom metrics would require extending the backend parsing logic in server/src/services/.

How do I update API credentials without restarting? Use the PUT /api/settings endpoint or the in-app settings page — runtime configuration is supported.

Conclusion

AgriciDaniel/on-page-seo is a pragmatic, engineer-focused solution to a genuine operational problem: running structured, large-scale SEO audits without surrendering data to third-party SaaS platforms or paying escalating per-seat fees. The 500-page ceiling, 74-metric depth, and Core Web Vitals integration provide sufficient coverage for most technical SEO workflows, while the React 19 + Express + SQLite stack keeps deployment and maintenance accessible to any team already working in the JavaScript^{↗ Bright Coding Blog} ecosystem.

It's best suited for: developers at product companies with in-house SEO needs, technical agencies serving privacy-conscious clients, and engineering teams building out marketing automation infrastructure. It's less appropriate for non-technical users seeking turnkey solutions or teams needing immediate competitive intelligence beyond on-page factors.

The project's active maintenance (last commit June 2026), public build documentation, and MIT licensing provide reasonable confidence for production adoption. For teams evaluating the tool, the fastest path to conviction is a local installation against a familiar site — the setup takes under ten minutes with valid API credentials.

Get started with AgriciDaniel/on-page-seo at https://github.com/AgriciDaniel/on-page-seo. For a broader publishing and content optimization pipeline, the maintainer also offers Rankenstein as a commercial extension.

Built by Agrici Daniel. Follow his YouTube channel for build tutorials or join the AI Marketing Hub community for automation discussions.