@rumenx/seo


A comprehensive TypeScript library for SEO analysis, content optimization, and meta tag generation with AI-powered suggestions.

✨ Features

- 🔍 Content Analysis: Deep analysis of HTML content, structure, and SEO metrics
- 🎯 SEO Recommendations: Automated suggestions for title, description, headings, and more
- 🤖 AI Integration: Support for OpenAI GPT-4.1, Claude 4, Gemini 1.5 Pro, xAI Grok, and Ollama for content generation
- 📊 SEO Scoring: Comprehensive scoring system with detailed breakdowns
- ⚡ Fast Mode: Optimized analysis for performance-critical applications
- 🏗️ Framework Ready: Built-in adapters for Express, Next.js, and Fastify
- 📝 TypeScript: Full type safety with extensive type definitions
- 🌐 Dual Module: Both ESM and CommonJS support
- 🚀 Zero Dependencies: Core functionality works without external dependencies
- 🔒 Security First: Secure HTML parsing and content analysis
- 📦 Batch Processing: Analyze multiple documents efficiently
- 💾 Caching System: Memory and Redis cache support for performance
- ⏱️ Rate Limiting: Protect API limits with built-in rate limiters
- 🔄 Provider Fallback: Automatic failover between AI providers
- 🏷️ Schema.org: Generate structured data for rich snippets
- 🔗 Fluent Interface: Method chaining for elegant code

📦 Installation

``bash
npm install @rumenx/seo
`

$3

For AI-powered content generation, install your preferred provider:

`bash


OpenAI (GPT-4.1, GPT-4.1-turbo)

`typescript
import { ContentAnalyzer } from '@rumenx/seo';

// Step 1: Analyze your content data
const analyzer = new ContentAnalyzer();
const postData = {
title: 'Complete Guide to SEO',
content: '

Your blog post content...

// Step 2: Generate optimized SEO data for templates
function generateSeoForPost(postData) {
const mockContent =

const html =

${postData.title}

`typescript
import { ContentAnalyzer } from '@rumenx/seo';

const analyzer = new ContentAnalyzer();
const analysis = analyzer.analyze(existingHtml);

console.log('📊 Analysis Results:');
console.log(Word count: ${analysis.wordCount});
console.log(Reading time: ${analysis.readingTime} minutes);
console.log(Keywords:, analysis.keywords.slice(0, 5));
console.log(SEO Score: ${analysis.seoMetrics.score}/100);
`

$3

`typescript
import { SeoManager } from '@rumenx/seo';

const seoManager = new SeoManager({
baseUrl: 'https://example.com',
mode: 'comprehensive',
});

const result = await seoManager.analyze(htmlContent, {
url: 'https://example.com/seo-guide',
});

// View recommendations
result.recommendations.forEach(rec => {
console.log(${rec.severity.toUpperCase()}: ${rec.message});
if (rec.suggestion) {
console.log(💡 Suggestion: ${rec.suggestion});
}
});
`

$3

`typescript
import { SeoManager } from '@rumenx/seo';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const seoManager = new SeoManager(config, openai);

// Generate optimized titles for your content
const titleSuggestions = await seoManager.generateSuggestions(analysis, 'title', {
maxTokens: 100,
temperature: 0.7,
});

console.log('🎯 Title Suggestions:');
titleSuggestions.forEach((title, i) => {
console.log(${i + 1}. ${title});
});
`

💡 How It Works

This library is designed for template-first SEO optimization:

1. Analyze your content data (from CMS, database, etc.)
2. Optimize SEO elements before rendering
3. Render templates with pre-optimized meta tags

This approach is more efficient than analyzing already-rendered HTML and allows you to optimize content for search engines before users see it.

🚀 Advanced Features

$3

Process multiple documents efficiently:

`typescript
import { SeoManager } from '@rumenx/seo';

const seoManager = new SeoManager(config);

// Analyze multiple documents in batch
const documents = [
{ id: 'post-1', content: htmlContent1, metadata: { title: 'Post 1' } },
{ id: 'post-2', content: htmlContent2, metadata: { title: 'Post 2' } },
{ id: 'post-3', content: htmlContent3, metadata: { title: 'Post 3' } },
];

const results = await seoManager.analyzeBatch(documents, {
fast: true, // Use fast mode for better performance
concurrency: 5, // Process 5 documents at a time
onProgress: (completed, total) => {
console.log(Progress: ${completed}/${total});
},
});

results.forEach(({ id, result, error }) => {
if (error) {
console.error(Failed to analyze ${id}:, error);
} else {
console.log(${id}: Score ${result.score.overall}/100);
}
});

// Generate SEO data for multiple documents with AI
const analyses = results.map(r => ({ id: r.id, analysis: r.result.analysis }));

const seoData = await seoManager.generateBatch(analyses, {
types: ['title', 'description', 'keywords'],
concurrency: 3,
onProgress: (completed, total) => {
console.log(Generated: ${completed}/${total});
},
});

seoData.forEach((data, id) => {
console.log(\nSEO for ${id}:);
console.log(Titles:, data.title);
console.log(Descriptions:, data.description);
console.log(Keywords:, data.keywords);
});
`

$3

Improve performance with built-in caching:

`typescript
import { SeoManager, MemoryCache, RedisCache } from '@rumenx/seo';

// Memory cache (for single instance)
const memoryCache = new MemoryCache({
ttl: 300, // 5 minutes
maxSize: 1000, // Maximum 1000 entries
enableStats: true,
});

// Redis cache (for distributed systems)
const redisCache = new RedisCache({
url: 'redis://localhost:6379',
ttl: 600, // 10 minutes
namespace: 'seo',
enableStats: true,
});

// Use cache with SeoManager
const config = {
baseUrl: 'https://example.com',
cache: memoryCache, // or redisCache
};

// Cache statistics
const stats = await memoryCache.getStats();
console.log(Cache hit rate: ${(stats.hitRate * 100).toFixed(2)}%);
console.log(Cache size: ${stats.size});

// Manual cache operations
await memoryCache.set('key', { data: 'value' }, 300);
const cached = await memoryCache.get('key');
await memoryCache.delete('key');

// Batch cache operations
const entries = new Map([
['key1', { data: 'value1' }],
['key2', { data: 'value2' }],
]);
await memoryCache.setMany(entries, 300);
const cachedData = await memoryCache.getMany(['key1', 'key2']);
`

$3

Protect your AI provider API limits:

`typescript
import { RateLimiter, RateLimiterManager } from '@rumenx/seo';

// Create rate limiter for OpenAI
const openaiLimiter = new RateLimiter({
maxRequests: 60, // 60 requests
windowMs: 60000, // per minute
maxConcurrent: 5, // max 5 concurrent requests
enableQueue: true, // queue excess requests
maxQueueSize: 100, // max 100 queued requests
});

// Use with AI provider
async function callAI() {
await openaiLimiter.acquire(); // Wait for rate limit slot
try {
const response = await aiProvider.generate(prompt);
return response;
} finally {
openaiLimiter.release(); // Release slot
}
}

// Check rate limiter status
console.log(Available tokens: ${openaiLimiter.getAvailableTokens()});
const stats = openaiLimiter.getStats();
console.log(Accepted: ${stats.acceptedRequests});
console.log(Rejected: ${stats.rejectedRequests});
console.log(Queued: ${stats.queuedRequests});

// Rate limiter manager for multiple providers
const manager = new RateLimiterManager();

manager.setLimiter(
'openai',
new RateLimiter({
maxRequests: 60,
windowMs: 60000,
})
);

manager.setLimiter(
'anthropic',
new RateLimiter({
maxRequests: 50,
windowMs: 60000,
})
);

const limiter = manager.getLimiter('openai');
await limiter.acquire();
`

$3

Automatic fallback between AI providers:

`typescript
import { AiProviderChain, OpenAiProvider, AnthropicProvider, GoogleAiProvider } from '@rumenx/seo';

// Create AI providers
const providers = [
new OpenAiProvider({ apiKey: process.env.OPENAI_API_KEY }),
new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
new GoogleAiProvider({ apiKey: process.env.GOOGLE_AI_API_KEY }),
];

// Create provider chain (tries each in order until success)
const providerChain = new AiProviderChain({
providers,
maxRetries: 2, // Retry each provider twice
timeout: 30000, // 30 second timeout per provider
onProviderFailed: (provider, error) => {
console.warn(Provider ${provider} failed:, error.message);
},
onProviderSuccess: (provider, response) => {
console.log(Provider ${provider} succeeded);
},
});

// Generate with automatic fallback
try {
const response = await providerChain.generate('Generate SEO title');
console.log('Generated:', response.content);
} catch (error) {
console.error('All providers failed:', error);
}

// Provider chain statistics
const chainStats = providerChain.getStats();
console.log(Success rate: ${chainStats.successfulRequests}/${chainStats.totalRequests});
console.log(Provider usage:, Object.fromEntries(chainStats.providerUsage));
console.log(Average response time: ${chainStats.averageResponseTime}ms);

// Dynamic provider management
providerChain.addProvider(new XAiProvider({ apiKey: process.env.XAI_API_KEY }), 1); // Add at priority 1
providerChain.removeProvider('google-ai');
providerChain.setProviderPriority('anthropic', 0); // Make Anthropic first
`

$3

Generate structured data for rich snippets:

`typescript
import { ArticleSchema, BreadcrumbListSchema, ProductSchema } from '@rumenx/seo';

// Article schema
const article = new ArticleSchema()
.setHeadline('Complete Guide to SEO Optimization')
.setDescription('Learn how to optimize your website for search engines')
.setImage('https://example.com/article-image.jpg')
.setDatePublished(new Date('2024-01-01'))
.setDateModified(new Date())
.setAuthor({
'@type': 'Person',
name: 'John Doe',
url: 'https://example.com/authors/john-doe',
})
.setPublisher({
'@type': 'Organization',
name: 'Example Inc',
logo: {
'@type': 'ImageObject',
url: 'https://example.com/logo.png',
},
});

// Breadcrumb schema
const breadcrumbs = new BreadcrumbListSchema()
.addItem('Home', 'https://example.com', 1)
.addItem('Blog', 'https://example.com/blog', 2)
.addItem('SEO Guide', 'https://example.com/blog/seo-guide', 3);

// Product schema
const product = new ProductSchema()
.setName('SEO Pro Tool')
.setImage('https://example.com/product.jpg')
.setDescription('Professional SEO analysis tool')
.setSKU('SEO-PRO-001')
.setBrand({ '@type': 'Brand', name: 'Example Inc' })
.setOffers({
'@type': 'Offer',
price: '99.00',
priceCurrency: 'USD',
availability: 'https://schema.org/InStock',
url: 'https://example.com/products/seo-pro',
})
.setAggregateRating({
'@type': 'AggregateRating',
ratingValue: 4.8,
reviewCount: 125,
});

// Generate JSON-LD
const articleJson = article.toJson();
const breadcrumbsJson = breadcrumbs.toJson();
const productJson = product.toJson();

// Use in HTML
const html =


;
`

$3

Chain methods for cleaner code:

`typescript
import { SeoManager } from '@rumenx/seo';

const seoManager = new SeoManager(config);

// Method chaining for configuration and analysis
const seoData = seoManager
.setAiProvider(openaiProvider)
.updateConfig({ mode: 'comprehensive' })
.analyze(htmlContent, metadata)
.generateAll();

console.log('Title:', seoData.title);
console.log('Description:', seoData.description);
console.log('Keywords:', seoData.keywords);
console.log('Score:', seoData.score.overall);
`

$3

See examples/simple-template-rendering.ts for a complete workflow demonstration.

$3

`typescript
// Express.js
app.get('/posts/:slug', async (req, res) => {
const postData = await getPostFromDatabase(req.params.slug);
const seoData = generateSeoForPost(postData);
const html = renderBlogPost(postData, seoData);
res.send(html);
});

// Next.js
export async function getServerSideProps({ params }) {
const postData = await getPostFromCMS(params.slug);
const seoData = generateSeoForPost(postData);

return { props: { postData, seoData } };
}
`

Content Analysis Utilities

The library provides comprehensive content analysis utilities:

`typescript
import { extractTextContent, extractHeadings, extractKeywords } from '@rumenx/seo';

const html = '

Title

Content...

// Extract keywords
const keywords = extractKeywords(text);
`

SEO Recommendations

Get automated SEO recommendations:

`typescript
const result = await seoManager.analyze(htmlContent);

result.recommendations.forEach(rec => {
console.log(${rec.severity}: ${rec.message});
console.log(Suggestion: ${rec.suggestion});
});
`

AI-Powered Suggestions

Generate content suggestions with AI:

`typescript
// Configure with AI provider
const seoManager = new SeoManager(config, aiProvider);

// Generate title suggestions
const titles = await seoManager.generateSuggestions(analysis, 'title', {
maxTokens: 100,
temperature: 0.7,
});

// Generate meta description suggestions
const descriptions = await seoManager.generateSuggestions(analysis, 'description');
`

API Reference

$3

- SeoManager: Main class for SEO analysis and content generation
- ContentAnalyzer: Standalone content analysis utilities

$3

- extractTextContent(html): Extract clean text from HTML
- extractHeadings(html): Extract heading structure
- extractImages(html): Analyze images and alt text
- extractKeywords(text): Extract relevant keywords
- calculateReadingTime(text): Calculate reading time

$3

The library includes comprehensive TypeScript types for all features:

- SeoConfig - Configuration options
- ContentAnalysis - Analysis results
- SeoRecommendation - Recommendation structure
- ImageAnalysis - Image analysis data
- SeoMetrics - SEO-specific metrics

Framework Integration

$3

`typescript
import express from 'express';
import { SeoManager } from '@rumenx/seo';

const app = express();
const seoManager = new SeoManager(config);

app.get('/analyze', async (req, res) => {
const result = await seoManager.analyze(req.body.html);
res.json(result);
});
`

$3

`typescript
import { SeoManager } from '@rumenx/seo';

export async function getServerSideProps({ req }) {
const seoManager = new SeoManager(config);
const analysis = await seoManager.analyze(pageContent);

return {
props: { seoData: analysis },
};
}
`

Configuration

`typescript
const config = {
baseUrl: 'https://example.com',
mode: 'comprehensive', // or 'fast'
aiProvider: 'openai',
validation: {
strictMode: true,
customRules: [],
},
cache: {
enabled: true,
ttl: 3600,
},
};
`

📚 Documentation

- API Reference - Complete API documentation
- Examples - Working code examples
- Changelog - Version history and updates

🔗 Related Projects

Check out our other Node.js tools that work great with @rumenx/seo`:

$3

- @rumenx/chatbot - AI-powered chatbot integration for Node.js applications
- @rumenx/sitemap - Dynamic sitemap generation and management
- @rumenx/feed - RSS/Atom feed generator for content syndication

$3

- php-seo - SEO analysis and optimization library for PHP
- go-seo _(Planned)_ - SEO analysis and optimization library for Go

These tools complement each other to provide a complete content management and SEO solution for modern web applications.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

- 🐛 Report Bugs
- 💡 Request Features
- 📖 Improve Docs
- ❓ Ask Questions

🔒 Security

Security is important to us. Please review our Security Policy and report vulnerabilities responsibly.

💝 Support This Project

If you find this library helpful, consider supporting its development:

- ⭐ Star the repository
- 💰 Sponsor on GitHub
- ☕ Buy me a coffee
- 📢 Share with others

📄 License

This project is licensed under the MIT License.

📞 Support & Community

- 📖 Documentation
- 🐛 Issue Tracker
- ✉️ Email Support

---

Made with ❤️ by Rumen Damyanov