Core Package Overview
The @capyseo/core package is the analysis engine powering Capyseo. It provides 46 SEO rules, AI integration, and multiple output formats.
Installation
npm install @capyseo/core
# or
bun add @capyseo/core
Quick Start
import { SEOAnalyzer } from '@capyseo/core';
const analyzer = new SEOAnalyzer();
const html = `
<!DOCTYPE html>
<html lang="en">
<head>
<title>My Page</title>
</head>
<body>
<h1>Hello World</h1>
</body>
</html>
`;
const report = await analyzer.analyzePage(html, 'https://example.com/');
console.log(`Score: ${report.score}/100`);
console.log(`Issues: ${report.issues.length}`);
Features
Feature
Description
46 SEO Rules Meta, images, headings, links, content, social, structured data, mobile, security, performance, URL
AI Integration Gemini, OpenAI, Anthropic, Ollama for suggestions
Multiple Reporters Console, JSON, HTML, CSV, SARIF
Live Checks Broken links, redirect chains, security headers
Lighthouse Optional Core Web Vitals metrics
Core Concepts
Rules
Rules check specific SEO aspects:
{
ruleId: 'meta-title',
severity: 'error',
message: 'Page title is too short (15 chars, minimum 30)',
suggestion: 'Add more descriptive text to the title'
}
Reports
Analysis returns a report:
{
url: 'https://example.com/',
timestamp: '2024-01-15T12:00:00.000Z',
score: 85,
issues: [...],
metrics: { lcp: 1200, cls: 0.05, ... } // Optional
}
Scoring
Score is 0-100 based on:
Errors: up to -40 points
Warnings: up to -35 points
Info: up to -15 points
Uses logarithmic scaling so each additional issue has diminishing impact.
Exports
// Main class
import { SEOAnalyzer } from '@capyseo/core';
// AI clients
import { createAIClient, GeminiProvider, OpenAIProvider } from '@capyseo/core';
// Reporters
import { consoleReporter, jsonReporter, htmlReporter } from '@capyseo/core';
// Utilities
import { analyzeReadability, parseSitemap, parseRobotsTxt } from '@capyseo/core';
// Types
import type { SEOReport, SEOIssue, CapyseoConfig } from '@capyseo/core';
Next Steps
