A comprehensive TypeScript package for AI-powered SEO optimization in Node.js applications. Framework-agnostic with built-in AI integration, Schema.org structured data, caching, batch processing, and 100% type safety.
npm install @rumenx/seo




A comprehensive TypeScript library for SEO analysis, content optimization, and meta tag generation with AI-powered suggestions.
- 🔍 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
``bash`
npm install @rumenx/seo
For AI-powered content generation, install your preferred provider:
`bashOpenAI (GPT-4.1, GPT-4.1-turbo)
npm install openai
$3
- Node.js: 18.x or higher
- TypeScript: 4.7 or higher (for TypeScript projects)
🚀 Quick Start
$3
The primary use case is to optimize content before rendering your templates:
`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...
',
tags: ['SEO', 'Web Development'],
};// Step 2: Generate optimized SEO data for templates
function generateSeoForPost(postData) {
const mockContent =
; const analysis = analyzer.analyze(mockContent);
return {
title: optimizeTitle(postData.title, analysis.keywords),
description: generateDescription(analysis.textContent),
keywords: [...postData.tags, ...analysis.keywords.slice(0, 5)],
};
}
// Step 3: Use optimized data in your template
const seoData = generateSeoForPost(postData);
const html =
;
`$3
For analyzing existing HTML content:
`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 text content
const text = extractTextContent(html);
// Extract headings
const headings = extractHeadings(html);
// 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 metricsFramework 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`:- @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
- 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.
We welcome contributions! Please see our Contributing Guide for details.
- 🐛 Report Bugs
- 💡 Request Features
- 📖 Improve Docs
- ❓ Ask Questions
Security is important to us. Please review our Security Policy and report vulnerabilities responsibly.
If you find this library helpful, consider supporting its development:
- ⭐ Star the repository
- 💰 Sponsor on GitHub
- ☕ Buy me a coffee
- 📢 Share with others
This project is licensed under the MIT License.
- 📖 Documentation
- 🐛 Issue Tracker
- ✉️ Email Support
---
Made with ❤️ by Rumen Damyanov