@power-seo/audit

Comprehensive SEO auditing with 0–100 scoring across four rule categories: meta tags, content quality, structural correctness, and performance optimization.

@power-seo/audit is a production-grade SEO audit engine that evaluates pages against a structured rule set and returns scored, actionable reports. A single call to auditPage produces a 0–100 overall score plus per-category breakdowns across meta tags, content quality, document structure, and performance — along with an issue list where every item carries a severity level (error, warning, info) and a human-readable message.

For site-wide audits, auditSite accepts an array of page inputs and returns an aggregated report with an average score, top-recurring issues across all pages, and individual page results. This makes it straightforward to build an SEO dashboard, a CI gate, or an automated reporting pipeline.

The four rule sets can also be called independently — runMetaRules, runContentRules, runStructureRules, and runPerformanceRules — so you can selectively run only the rules relevant to your use case without paying for the full audit overhead.

Zero runtime dependencies — entirely local, synchronous computation; no external API required.

Why @power-seo/audit?

| | Without | With | | ------------------ | ------------------ | --------------------------------------------------- | | Meta tag audit | ❌ Manual checking | ✅ 0–100 scored across 4 rule categories | | Site-wide audit | ❌ Page-by-page | ✅ auditSite() — aggregate + per-page results | | Rule granularity | ❌ Pass/fail only | ✅ error / warning / info / pass severity | | Content analysis | ❌ Eye-check | ✅ Word count, keyphrase density, readability | | CI integration | ❌ Manual review | ✅ Node.js script with configurable score threshold | | Framework support | ❌ WordPress-only | ✅ Framework-agnostic, runs anywhere | | TypeScript support | ❌ Untyped | ✅ Full type coverage for all inputs and results |

Features

• Single-page audit — auditPage(input) returns an overall 0–100 score and a categories object with individual scores for meta, content, structure, and performance
• Site-wide audit — auditSite(input) audits multiple pages and returns aggregated average score, top issues by frequency, and per-page results
• Meta rules — title presence and length (50–60 chars), meta description presence and length (120–158 chars), canonical tag validation, robots meta directives, Open Graph completeness (og:title, og:description, og:image, og:url)
• Content rules — word count thresholds (thin content detection), focus keyphrase presence in title/description/first paragraph/headings, keyphrase density analysis, readability score integration
• Structure rules — single H1 validation, heading hierarchy (no skipped levels), image alt text completeness, internal link count, external link presence, JSON-LD schema validation
• Performance rules — image format optimization recommendations (JPEG vs WebP/AVIF), missing width/height attributes on images, absence of resource hints (preconnect, preload), unoptimized third-party script patterns
• Four severity levels — error (critical issues that directly hurt rankings), warning (sub-optimal practices), info (improvement opportunities), pass (checks that passed)
• Category-level scores — each of the four categories produces its own 0–100 score so you can prioritize by weakest category
• Composable rule sets — call individual rule runners (runMetaRules, runContentRules, runStructureRules, runPerformanceRules) for selective auditing
• Type-safe throughout — complete TypeScript types for inputs, results, issues, categories, and severities
• Zero network calls — entirely local, synchronous computation; no external API required

Comparison

| Feature | @power-seo/audit | Screaming Frog | Lighthouse | next-seo | ahrefs site audit | | --------------------- | :--------------: | :------------: | :--------: | :------: | :---------------: | | Programmatic API | ✅ | ❌ | Partial | ❌ | ❌ | | 4 rule categories | ✅ | Partial | Partial | ❌ | Partial | | 0–100 scored output | ✅ | ❌ | ✅ | ❌ | ✅ | | Site-wide aggregation | ✅ | ✅ | ❌ | ❌ | ✅ | | CI/CD integration | ✅ | ❌ | Partial | ❌ | ❌ | | Zero network calls | ✅ | ❌ | Partial | ✅ | ❌ | | TypeScript-first | ✅ | ❌ | ❌ | Partial | ❌ | | Tree-shakeable | ✅ | ❌ | ❌ | ❌ | ❌ |

Installation

npm install @power-seo/audit

yarn add @power-seo/audit

pnpm add @power-seo/audit

Quick Start

import { auditPage } from '@power-seo/audit';

const result = auditPage({
  url: 'https://example.com/blog/react-seo-guide',
  title: 'React SEO Guide — Best Practices for 2026',
  metaDescription:
    'Learn how to optimize React applications for search engines with meta tags, structured data, and Core Web Vitals improvements.',
  canonical: 'https://example.com/blog/react-seo-guide',
  robots: 'index, follow',
  content: '<h1>React SEO Guide</h1><p>Search engine optimization for React apps...</p>',
  headings: ['h1:React SEO Guide', 'h2:Why SEO Matters for React', 'h2:Meta Tags in React'],
  images: [{ src: '/hero.webp', alt: 'React SEO guide illustration' }],
  internalLinks: ['/blog', '/docs/meta-tags'],
  externalLinks: ['https://developers.google.com/search'],
  focusKeyphrase: 'react seo',
  wordCount: 1850,
});

console.log(result.score); // e.g. 84
console.log(result.categories);
// { meta: { score: 90, passed: 9, warnings: 1, errors: 0 }, content: { score: 82, ... }, ... }
console.log(result.rules);
// [
//   { id: 'meta-description-length', category: 'meta', severity: 'warning', title: '...', description: '...' },
//   { id: 'content-word-count', category: 'content', severity: 'pass', ... },
// ]

Usage

Page Audit

auditPage is the primary entry point for single-page evaluation. It runs all four rule sets and computes a weighted overall score.

import { auditPage } from '@power-seo/audit';
import type { PageAuditInput, PageAuditResult } from '@power-seo/audit';

const input: PageAuditInput = {
  url: 'https://example.com/products/widget',
  title: 'Premium Widget — Buy Online | Example',
  metaDescription:
    'Buy our premium widget online. Free shipping on orders over $50. Trusted by 10,000+ customers.',
  canonical: 'https://example.com/products/widget',
  robots: 'index, follow',
  openGraph: {
    title: 'Premium Widget',
    description: 'Buy our premium widget with free shipping.',
    image: 'https://example.com/images/widget-og.jpg',
  },
  content: '<h1>Premium Widget</h1><p>Our best-selling product...</p>',
  headings: ['h1:Premium Widget', 'h2:Features', 'h2:Customer Reviews'],
  images: [
    { src: '/images/widget.jpg', alt: 'Premium widget product photo' },
    { src: '/images/widget-detail.jpg', alt: '' },
  ],
  internalLinks: ['/products', '/cart', '/about'],
  externalLinks: [],
  focusKeyphrase: 'premium widget',
  wordCount: 620,
};

const result: PageAuditResult = auditPage(input);

// Filter rules by severity
const errors = result.rules.filter((r) => r.severity === 'error');
const warnings = result.rules.filter((r) => r.severity === 'warning');

console.log(`Score: ${result.score}/100`);
console.log(`Errors: ${errors.length}, Warnings: ${warnings.length}`);

Site Audit

auditSite runs page audits across an entire array of pages and returns aggregated statistics.

import { auditSite } from '@power-seo/audit';
import type { SiteAuditInput, SiteAuditResult } from '@power-seo/audit';

const siteInput: SiteAuditInput = {
  pages: [page1Input, page2Input, page3Input],
};

const report: SiteAuditResult = auditSite(siteInput);

console.log(`Average score: ${report.score}/100`);
console.log(`Pages audited: ${report.totalPages}`);
console.log('Top issues across site:');
report.topIssues.forEach(({ id, title, severity }) => {
  console.log(`  ${id} (${title}) [${severity}]`);
});

// Access individual page results
report.pageResults.forEach(({ url, score, rules }) => {
  const issues = rules.filter((r) => r.severity === 'error' || r.severity === 'warning');
  console.log(`${url}: ${score}/100 (${issues.length} issues)`);
});

Individual Rule Sets

Run only the rules you need without executing the full audit pipeline.

import {
  runMetaRules,
  runContentRules,
  runStructureRules,
  runPerformanceRules,
} from '@power-seo/audit';
import type { PageAuditInput, CategoryResult } from '@power-seo/audit';

const input: PageAuditInput = {
  /* ... */
};

// Run only meta checks — title, description, canonical, robots, OG
const metaRules = runMetaRules(input);
const errors = metaRules.filter((r) => r.severity === 'error');
const passes = metaRules.filter((r) => r.severity === 'pass');
console.log(`Meta: ${passes.length} passed, ${errors.length} errors`);
metaRules.forEach((r) => console.log(`  [${r.severity}] ${r.title}: ${r.description}`));

// Run only content checks — word count, keyphrase, readability
const contentRules = runContentRules(input);

// Run only structure checks — headings, images, links, schema
const structureRules = runStructureRules(input);

// Run only performance checks — image formats, resource hints
const perfRules = runPerformanceRules(input);

Processing Audit Issues

Issues can be filtered, grouped, and sorted for display in dashboards or reports.

import { auditPage } from '@power-seo/audit';
import type { AuditSeverity } from '@power-seo/audit';

const result = auditPage(input);

// Group rules by category
const byCategory = result.rules.reduce(
  (acc, rule) => {
    acc[rule.category] = acc[rule.category] ?? [];
    acc[rule.category]!.push(rule);
    return acc;
  },
  {} as Record<string, typeof result.rules>,
);

// Priority order: errors first, then warnings, then info, then pass
const prioritized = [...result.rules].sort((a, b) => {
  const order: Record<AuditSeverity, number> = { error: 0, warning: 1, info: 2, pass: 3 };
  return order[a.severity] - order[b.severity];
});

// Check if page passes a minimum score threshold
const MINIMUM_SCORE = 70;
if (result.score < MINIMUM_SCORE) {
  throw new Error(`SEO audit failed: score ${result.score} is below minimum ${MINIMUM_SCORE}`);
}

Using with CI/CD

Use auditPage or auditSite in a Node.js CI script to block deployments when scores fall below a threshold.

// scripts/seo-audit.ts
import { auditSite } from '@power-seo/audit';
import { pages } from './test-pages.js';

const report = auditSite({ pages });

const SCORE_THRESHOLD = 75;
const ALLOWED_ERRORS = 0;

const totalErrors = report.pageResults.flatMap((p) =>
  p.rules.filter((r) => r.severity === 'error'),
).length;

if (report.score < SCORE_THRESHOLD || totalErrors > ALLOWED_ERRORS) {
  console.error(`SEO audit FAILED`);
  console.error(`  Average score: ${report.score} (min: ${SCORE_THRESHOLD})`);
  console.error(`  Critical errors: ${totalErrors} (max: ${ALLOWED_ERRORS})`);
  process.exit(1);
}

console.log(`SEO audit PASSED — average score: ${report.score}/100`);

API Reference

auditPage(input)

| Parameter | Type | Required | Description | | ----------------------- | ----------------------------------------------------- | -------- | ------------------------------------------------------------- | | input.url | string | ✅ | Canonical URL of the page being audited | | input.title | string | — | Page <title> tag content | | input.metaDescription | string | — | Content of the meta[name="description"] tag | | input.canonical | string | — | Canonical URL from link[rel="canonical"] | | input.robots | string | — | Content of meta[name="robots"] tag (e.g. 'index, follow') | | input.openGraph | { title?, description?, image? } | — | Open Graph tag values | | input.content | string | — | Full HTML/text content of the page body | | input.headings | string[] | — | Headings as 'h1:text' / 'h2:text' strings | | input.images | Array<{ src: string; alt?: string; size?: number }> | — | Images extracted from the page | | input.internalLinks | string[] | — | Internal link href values found on the page | | input.externalLinks | string[] | — | External link href values found on the page | | input.schema | SchemaBase[] | — | JSON-LD schema objects present on the page | | input.focusKeyphrase | string | — | Focus keyphrase for content analysis | | input.wordCount | number | — | Word count proxy — used when content is not provided | | input.keywordDensity | number | — | Keyword density % proxy — used when content is not provided | | input.statusCode | number | — | HTTP status code of the page | | input.responseTime | number | — | Page response time in milliseconds | | input.contentLength | number | — | Content length in bytes |

Returns PageAuditResult:

| Property | Type | Description | | ----------------- | --------------------------------------- | ---------------------------------------------------------------- | | url | string | The audited page URL | | score | number | Overall weighted score 0–100 | | categories | Record<AuditCategory, CategoryResult> | Per-category scores with score, passed, warnings, errors | | rules | AuditRule[] | Flat array of all rule results across all categories | | recommendations | string[] | Human-readable descriptions of errors and warnings |

auditSite(input)

| Parameter | Type | Required | Description | | ---------------- | ------------------ | -------- | --------------------------------------------- | | input.pages | PageAuditInput[] | ✅ | Array of page audit inputs to evaluate | | input.hostname | string | — | Optional domain for link analysis and context |

Returns SiteAuditResult:

| Property | Type | Description | | ------------- | --------------------------------------- | --------------------------------------------------------- | | score | number | Mean score across all pages (0–100) | | totalPages | number | Total number of pages audited | | pageResults | PageAuditResult[] | Individual page audit results | | topIssues | AuditRule[] | Most frequently occurring non-pass rules across all pages | | summary | Record<AuditCategory, CategoryResult> | Aggregated category scores across all pages |

runMetaRules(input) / runContentRules(input) / runStructureRules(input) / runPerformanceRules(input)

Each rule runner accepts a PageAuditInput and returns AuditRule[]:

| Property | Type | Description | | ------------- | --------------- | ----------------------------------------------------------- | | id | string | Unique rule identifier (e.g. 'meta-title-length') | | category | AuditCategory | 'meta' | 'content' | 'structure' | 'performance' | | title | string | Short human-readable rule name | | description | string | Detailed description of the finding | | severity | AuditSeverity | 'error' | 'warning' | 'info' | 'pass' |

Types

import type {
  AuditCategory, // 'meta' | 'content' | 'structure' | 'performance'
  AuditSeverity, // 'error' | 'warning' | 'info' | 'pass'
  AuditRule, // { id, category, title, description, severity }
  PageAuditInput, // Full page input object (see auditPage parameters above)
  PageAuditResult, // { url, score, categories, rules, recommendations }
  CategoryResult, // { score: number; passed: number; warnings: number; errors: number }
  SiteAuditInput, // { pages: PageAuditInput[] }
  SiteAuditResult, // { score, totalPages, pageResults, topIssues, summary }
} from '@power-seo/audit';

Use Cases

• Headless CMS — score pages before publish; block publication if score drops below threshold
• Next.js / Remix apps — run server-side audit per route and expose scores in admin dashboards
• CI/CD quality gates — block deploys when audit scores fall below a configurable threshold
• SaaS platforms — provide per-client SEO health scores across all managed pages
• Reporting tools — generate structured audit reports for agencies delivering SEO as a service

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero external runtime dependencies — entirely local, synchronous computation
• Framework-agnostic — works in Next.js, Remix, Vite, Express, Edge runtimes, or CI scripts
• SSR compatible — no browser-specific APIs; safe for server-side use
• Edge runtime safe — no Node.js-specific APIs; runs in Cloudflare Workers, Vercel Edge, Deno
• Tree-shakeable — "sideEffects": false with named exports per rule runner
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for SSR, Edge, and server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

| Package | Install | Description | | ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------- | | @power-seo/core | npm i @power-seo/core | Framework-agnostic utilities, types, validators, and constants | | @power-seo/react | npm i @power-seo/react | React SEO components — meta, Open Graph, Twitter Card, breadcrumbs | | @power-seo/meta | npm i @power-seo/meta | SSR meta helpers for Next.js App Router, Remix v2, and generic SSR | | @power-seo/schema | npm i @power-seo/schema | Type-safe JSON-LD structured data — 23 builders + 22 React components | | @power-seo/content-analysis | npm i @power-seo/content-analysis | Yoast-style SEO content scoring engine with React components | | @power-seo/readability | npm i @power-seo/readability | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI | | @power-seo/preview | npm i @power-seo/preview | SERP, Open Graph, and Twitter/X Card preview generators | | @power-seo/sitemap | npm i @power-seo/sitemap | XML sitemap generation, streaming, index splitting, and validation | | @power-seo/redirects | npm i @power-seo/redirects | Redirect engine with Next.js, Remix, and Express adapters | | @power-seo/links | npm i @power-seo/links | Link graph analysis — orphan detection, suggestions, equity scoring | | @power-seo/audit | npm i @power-seo/audit | Full SEO audit engine — meta, content, structure, performance rules | | @power-seo/images | npm i @power-seo/images | Image SEO — alt text, lazy loading, format analysis, image sitemaps | | @power-seo/ai | npm i @power-seo/ai | LLM-agnostic AI prompt templates and parsers for SEO tasks | | @power-seo/analytics | npm i @power-seo/analytics | Merge GSC + audit data, trend analysis, ranking insights, dashboard | | @power-seo/search-console | npm i @power-seo/search-console | Google Search Console API — OAuth2, service account, URL inspection | | @power-seo/integrations | npm i @power-seo/integrations | Semrush and Ahrefs API clients with rate limiting and pagination | | @power-seo/tracking | npm i @power-seo/tracking | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License