@power-seo/core

@power-seo/core

Framework-agnostic SEO utilities, types, and engines — the shared foundation of the entire @power-seo ecosystem, usable as a standalone TypeScript library that works anywhere.

@power-seo/core is the foundational library shared by all 17 @power-seo packages. It delivers pixel-accurate meta validators, structured meta and link tag builders, URL normalization, keyword density analysis, text statistics, Open Graph and Twitter Card builders, robots directive generation, title template engines, and a token-bucket rate limiter — all in a single zero-dependency TypeScript package. Think of it as combining next-seo, seo-utils, keyword-density, url-normalize, and text-statistics into one unified, tree-shakeable library that runs in Next.js, Remix, Vite, vanilla Node.js, Cloudflare Workers, and Vercel Edge. All 8 utility modules are fully configurable and independently importable.

Zero runtime dependencies — installs clean with nothing else to pull in.

Why @power-seo/core?

	Without	With
Meta tag building	❌ Hand-written HTML strings	✅ Type-safe buildMetaTags() with OG + Twitter
Title validation	❌ Character count only	✅ Pixel-accurate SERP width via validateTitle()
Keyword density	❌ Manual regex counting	✅ calculateKeywordDensity() with density %
URL canonicalization	❌ String manipulation	✅ resolveCanonical() with full normalization
Text statistics	❌ Multiple separate packages	✅ getTextStatistics() — words, sentences, syllables
Robots directives	❌ Concatenated strings	✅ Type-safe buildRobotsContent() builder
Title templates	❌ Manual string interpolation	✅ createTitleTemplate() with site-wide defaults
Rate limiting	❌ No built-in utility	✅ Token bucket createTokenBucket() for API calls
TypeScript types	❌ Duplicated across packages	✅ 25+ shared interfaces for the full ecosystem

Features

• Meta tag builder — buildMetaTags() generates typed arrays of meta tags from a structured SEOConfig
• Open Graph builder — buildOpenGraphTags() with full support for article, profile, book, video, and music OG types
• Twitter Card builder — buildTwitterTags() for summary, large image, player, and app card types
• Hreflang builder — buildHreflangTags() generates <link rel="alternate"> tags for multi-language pages
• Title template engine — applyTitleTemplate() and createTitleTemplate() with %variable% substitution and separator cleanup
• Pixel-accurate meta validators — validateTitle() and validateMetaDescription() measure real SERP pixel widths using Arial font metrics
• URL utilities — resolveCanonical(), normalizeUrl(), toSlug(), stripTrackingParams(), extractSlug(), and more
• Text statistics engine — getTextStatistics() returns word, sentence, paragraph, syllable, and character counts from HTML
• Keyword density calculator — calculateKeywordDensity() and analyzeKeyphraseOccurrences() for single and multi-word keyphrases
• Robots directive builder — buildRobotsContent() and parseRobotsContent() for structured robots meta directives
• Rate limiting — token bucket implementation with createTokenBucket(), consumeToken(), and getWaitTime()
• SEO constants — exported TITLE_MAX_PIXELS, META_DESCRIPTION_MAX_PIXELS, KEYWORD_DENSITY, READABILITY, OG_IMAGE, AI_CRAWLERS, and SCHEMA_TYPES
• 25+ shared TypeScript types — SEOConfig, MetaTag, LinkTag, OpenGraphConfig, TwitterCardConfig, ContentAnalysisInput, and more
• Framework-agnostic — works in Next.js, Remix, Gatsby, Vite, vanilla Node.js, Edge
• Tree-shakeable — "sideEffects": false with named exports per module; import only what you use

Comparison

Feature	@power-seo/core	next-seo	seo-utils	keyword-density	text-statistics
Meta tag builder	✅	Partial	❌	❌	❌
Pixel-accurate title/meta validation	✅	❌	❌	❌	❌
Open Graph builder	✅	Partial	❌	❌	❌
Twitter Card builder	✅	Partial	❌	❌	❌
Keyphrase density calculator	✅	❌	❌	✅	❌
Keyphrase occurrence analysis	✅	❌	❌	❌	❌
Robots directive builder	✅	Partial	❌	❌	❌
URL normalization + slug	✅	❌	Partial	❌	❌
Text statistics engine	✅	❌	❌	❌	Partial
Title template engine	✅	Partial	❌	❌	❌
Hreflang builder	✅	Partial	❌	❌	❌
Rate limiting utility	✅	❌	❌	❌	❌
25+ shared SEO types	✅	Partial	❌	❌	❌
TypeScript-first	✅	Partial	❌	❌	❌
Zero runtime dependencies	✅	❌	❌	❌	❌

Installation

npm install @power-seo/core

yarn add @power-seo/core

pnpm add @power-seo/core

Quick Start

import { buildMetaTags, buildLinkTags, validateTitle, resolveCanonical } from '@power-seo/core';

const tags = buildMetaTags({
  description: 'Master SEO in Next.js with structured data and meta tags.',
  openGraph: {
    type: 'article',
    title: 'Next.js SEO Guide',
    images: [{ url: 'https://example.com/og.jpg', width: 1200, height: 630 }],
  },
  twitter: { cardType: 'summary_large_image', site: '@mysite' },
});

const links = buildLinkTags({
  canonical: resolveCanonical('https://example.com', '/nextjs-seo'),
});

const titleCheck = validateTitle('Next.js SEO Best Practices Guide');
console.log(titleCheck.valid); // true
console.log(titleCheck.pixelWidth); // ~291 (well under 580px limit)

Validation severity levels:

• error — field is missing or critically invalid
• warning — field exists but fails recommended limits
• info — field passes all checks

Usage

Building Meta Tags

buildMetaTags() assembles a flat array of MetaTag objects from a typed SEOConfig. Frameworks render these into actual <meta> HTML elements.

import { buildMetaTags } from '@power-seo/core';

const tags = buildMetaTags({
  description: 'A TypeScript-first SEO library for modern JavaScript frameworks.',
  robots: { index: true, follow: true, maxSnippet: 150, maxImagePreview: 'large' },
  openGraph: {
    type: 'website',
    title: '@power-seo/core',
    siteName: 'My Site',
    locale: 'en_US',
    images: [{ url: 'https://example.com/og.jpg', width: 1200, height: 630, alt: 'SEO Core' }],
  },
  twitter: {
    cardType: 'summary_large_image',
    site: '@mysite',
    creator: '@author',
    image: 'https://example.com/twitter.jpg',
  },
});
// tags → MetaTag[] — pass to your framework's meta renderer

Validating Titles and Meta Descriptions

validateTitle() and validateMetaDescription() calculate the real pixel width Google uses for SERP truncation — not just character count.

import { validateTitle, validateMetaDescription } from '@power-seo/core';

const title = validateTitle('Best Running Shoes for Beginners — 2026 Guide');
// { valid: true, severity: 'info', charCount: 46, pixelWidth: 316.8 }

const meta = validateMetaDescription('Discover expert-reviewed running shoes for beginners.');
// { valid: true, severity: 'warning', charCount: 52, pixelWidth: 335.3 }
// → short (under 120 chars), suggests expanding to 120–160 chars

URL Utilities

import {
  resolveCanonical,
  normalizeUrl,
  toSlug,
  stripTrackingParams,
  extractSlug,
  isAbsoluteUrl,
} from '@power-seo/core';

resolveCanonical('https://example.com', '/blog/post');
// => "https://example.com/blog/post"

toSlug('My Blog Post Title! — 2026');
// => "my-blog-post-title-2026"

stripTrackingParams('https://example.com/page?utm_source=twitter&id=123');
// => "https://example.com/page?id=123"

extractSlug('https://example.com/blog/my-post');
// => "my-post"

Keyword Density Analysis

import { calculateKeywordDensity, analyzeKeyphraseOccurrences } from '@power-seo/core';

const density = calculateKeywordDensity('react seo', bodyHtml);
// { keyword: 'react seo', count: 4, density: 1.8, totalWords: 450 }

const occurrences = analyzeKeyphraseOccurrences({
  keyphrase: 'react seo',
  title: 'React SEO Best Practices',
  metaDescription: 'Learn React SEO...',
  content: htmlString,
  slug: 'react-seo',
  images: [{ alt: 'React SEO diagram' }],
});
// { inTitle: true, inH1: true, inFirstParagraph: true, density: 1.8, ... }

Text Statistics

import { getTextStatistics, stripHtml, getWords, getSentences } from '@power-seo/core';

const stats = getTextStatistics('<h1>Hello</h1><p>This is a test sentence. And another one.</p>');
// {
//   wordCount: 9,
//   sentenceCount: 2,
//   paragraphCount: 1,
//   syllableCount: 11,
//   characterCount: 42,
//   avgWordsPerSentence: 4.5,
//   avgSyllablesPerWord: 1.22
// }

Robots Directives

import { buildRobotsContent, parseRobotsContent } from '@power-seo/core';

buildRobotsContent({ index: false, follow: true, maxSnippet: 150, maxImagePreview: 'large' });
// => "noindex, follow, max-snippet:150, max-image-preview:large"

parseRobotsContent('noindex, follow, max-snippet:150');
// => { index: false, follow: true, maxSnippet: 150 }

Title Template Engine

import { createTitleTemplate, applyTitleTemplate } from '@power-seo/core';

const makeTitle = createTitleTemplate({ siteName: 'My Site', separator: '—' });
makeTitle('About Us'); // => "About Us — My Site"
makeTitle('Contact', { separator: '|' }); // => "Contact | My Site"

applyTitleTemplate('%title% | %siteName% — Page %page%', {
  title: 'Blog',
  siteName: 'My Site',
  page: 2,
});
// => "Blog | My Site — Page 2"

Rate Limiting

import { createTokenBucket, consumeToken, getWaitTime, sleep } from '@power-seo/core';

const bucket = createTokenBucket(60); // 60 requests per minute

async function callApi() {
  if (!consumeToken(bucket)) {
    const waitMs = getWaitTime(bucket);
    await sleep(waitMs);
  }
  // make your rate-limited API call
}

Inside a CI Content Quality Gate

Block deploys when keyword density or word count fail:

import { calculateKeywordDensity, getTextStatistics } from '@power-seo/core';

const stats = getTextStatistics(bodyHtml);
const density = calculateKeywordDensity(keyphrase, bodyHtml);

if (stats.wordCount < 300) {
  console.error(`✗ Word count too low: ${stats.wordCount} (minimum 300)`);
  process.exit(1);
}

if (density.density < 0.5 || density.density > 2.5) {
  console.error(`✗ Keyword density out of range: ${density.density}% (target 0.5–2.5%)`);
  process.exit(1);
}

API Reference

Entry Points

Import	Description
@power-seo/core	All utilities, types, constants, builders, and validators

Meta Builder Functions

Function	Description
buildMetaTags(config)	Build MetaTag[] array from SEOConfig
buildLinkTags(config)	Build LinkTag[] including canonical and hreflang
buildOpenGraphTags(og)	Build Open Graph MetaTag[] from OpenGraphConfig
buildTwitterTags(twitter)	Build Twitter Card MetaTag[] from TwitterCardConfig
buildHreflangTags(alternates)	Build hreflang LinkTag[] from HreflangConfig[]
resolveTitle(config)	Resolve final title applying template if set

Meta Validator Functions

Function	Description
validateTitle(title)	Validate title — char count, pixel width, severity
validateMetaDescription(desc)	Validate meta description — char count, pixel width, severity
calculatePixelWidth(text)	Calculate SERP pixel width using Arial font metrics

URL Utility Functions

Function	Description
resolveCanonical(base, path?)	Resolve and normalize a canonical URL
normalizeUrl(url)	Remove default ports, double slashes, trailing slashes
ensureTrailingSlash(url)	Add trailing slash to non-file URLs
removeTrailingSlash(url)	Strip trailing slash from a URL
stripQueryParams(url, keep?)	Remove all or selected query parameters
stripTrackingParams(url)	Remove UTM, fbclid, gclid, and other tracking params
extractSlug(url)	Extract the last path segment as a slug
isAbsoluteUrl(url)	Check whether a URL is absolute
toSlug(text)	Convert any string to a URL-safe slug

Text Statistics Functions

Function	Description
getTextStatistics(content)	Full stats — word, sentence, paragraph, syllable counts
stripHtml(html)	Strip HTML tags, decode entities, return plain text
getWords(text)	Split text into individual words
getSentences(text)	Split text into sentences
getParagraphs(html)	Extract paragraph blocks from HTML
countSyllables(word)	Count syllables in a single word
countTotalSyllables(text)	Count total syllables across all words in text

Keyword Density Functions

Function	Description
calculateKeywordDensity(keyword, content)	Density %, occurrence count, word total
countKeywordOccurrences(text, keyword)	Count keyword occurrences (case-insensitive, word-boundary)
analyzeKeyphraseOccurrences(config)	Full occurrence map — title, H1, meta, slug, alt text

Robots Builder Functions

Function	Description
buildRobotsContent(directive)	Serialize RobotsDirective to robots meta content string
parseRobotsContent(content)	Parse robots meta content string to RobotsDirective

Title Template Functions

Function	Description
applyTitleTemplate(template, vars)	Apply %variable% substitution to a title template
createTitleTemplate(defaults)	Create a reusable title factory with site-wide defaults

Rate Limiting Functions

Function	Description
createTokenBucket(requestsPerMinute)	Create a token bucket with capacity and refill rate
consumeToken(bucket)	Consume one token; returns true if allowed
getWaitTime(bucket)	Milliseconds to wait before next allowed request
sleep(ms)	Promise-based sleep utility

Constants

Constant	Value	Description
TITLE_MAX_PIXELS	580	Google SERP max title display width (pixels)
TITLE_MAX_LENGTH	60	Recommended max title character length
TITLE_MIN_LENGTH	50	Recommended min title character length
META_DESCRIPTION_MAX_PIXELS	920	Google SERP max meta description width (pixels)
META_DESCRIPTION_MAX_LENGTH	160	Recommended max meta description length
META_DESCRIPTION_MIN_LENGTH	120	Recommended min meta description length
MIN_WORD_COUNT	300	Minimum word count to avoid thin content
RECOMMENDED_WORD_COUNT	1000	Recommended word count for blog posts
MAX_URL_LENGTH	75	Maximum recommended URL length for SEO
KEYWORD_DENSITY	{ MIN: 0.5, MAX: 2.5, OPTIMAL: 1.5 }	Optimal keyword density range (%)
READABILITY	{ FLESCH_EASE_GOOD: 60, MAX_SENTENCE_LENGTH: 20, ... }	Readability scoring thresholds
OG_IMAGE	{ WIDTH: 1200, HEIGHT: 630, ASPECT_RATIO: 1.91 }	Open Graph recommended image dimensions
TWITTER_IMAGE	{ SUMMARY: { WIDTH: 144, HEIGHT: 144 }, SUMMARY_LARGE: { WIDTH: 800, HEIGHT: 418 } }	Twitter Card recommended image dimensions
AI_CRAWLERS	['GPTBot', 'ClaudeBot', 'CCBot', ...]	Common AI crawler user agents
SCHEMA_TYPES	['Article', 'Product', 'FAQPage', ...]	Common Schema.org types used in SEO

Types

Type	Description
SEOConfig	Full SEO configuration with title, meta, robots, OG, Twitter
MetaTag	{ name?, property?, httpEquiv?, content }
LinkTag	{ rel, href, hreflang?, type?, sizes?, media? }
OpenGraphConfig	OG configuration with type, images, videos, article, profile
OpenGraphType	'website' | 'article' | 'book' | 'profile' | 'product' | ...
OpenGraphImage	{ url, secureUrl?, type?, width?, height?, alt? }
TwitterCardConfig	Twitter Card with card type, site, image, player, app
TwitterCardType	'summary' | 'summary_large_image' | 'app' | 'player'
RobotsDirective	{ index?, follow?, noarchive?, maxSnippet?, maxImagePreview?, ... }
HreflangConfig	{ hrefLang, href }
ContentAnalysisInput	Input for content analysis — title, meta, content, keyphrase
ContentAnalysisOutput	Output with score, maxScore, results, recommendations
AnalysisResult	{ id, title, description, status, score, maxScore }
AnalysisStatus	'good' | 'ok' | 'poor'
ReadabilityInput	{ content, locale? }
ReadabilityOutput	Flesch scores, passive voice %, transition word %
TextStatistics	{ wordCount, sentenceCount, paragraphCount, syllableCount, characterCount, ... }
SitemapURL	{ loc, lastmod?, changefreq?, priority?, images?, videos?, news? }
SitemapConfig	{ hostname, urls, maxUrlsPerSitemap?, outputDir? }
RedirectRule	{ source, destination, statusCode, isRegex? }
SchemaBase	{ '@context'?, '@type', '@id'?, [key]: unknown }
SchemaGraphConfig	{ '@context': 'https://schema.org', '@graph': SchemaBase[] }
KeywordDensityResult	{ keyword, count, density, totalWords }
KeyphraseOccurrences	Full occurrence map — title, H1, meta, slug, alt text, density
TokenBucket	{ tokens, lastRefill, maxTokens, refillRate }
ValidationResult	{ valid, severity, message, charCount?, pixelWidth? }
ValidationSeverity	'error' | 'warning' | 'info'
TitleTemplateVars	{ title?, siteName?, separator?, tagline?, page?, [key]: string | number }

Use Cases

• @power-seo packages — all 17 packages use @power-seo/core as a peer dependency for shared types, constants, and utilities
• Custom SEO libraries — build your own SEO tooling on top of core's typed primitives without starting from scratch
• Next.js / Remix apps — use buildMetaTags() and buildLinkTags() server-side in route handlers or layout components
• Content editors — validate title and meta description SERP pixel widths in real time before publishing
• CI content quality gates — check keyword density and word count programmatically in build pipelines
• eCommerce product pages — validate product titles, descriptions, and slug quality at scale
• Rate-limited API integrations — use the token bucket to respect rate limits for Google Search Console, Semrush, or Ahrefs APIs
• Headless CMS plugins — use analyzeKeyphraseOccurrences() to show Yoast-style keyphrase feedback to editors

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero runtime dependencies — ships clean with nothing else to install
• Framework-agnostic — works in any JavaScript environment with no assumptions about React, Vue, or any framework
• SSR compatible — safe to run in Next.js Server Components, Remix loaders, or Express handlers
• Edge runtime safe — no Node.js-specific APIs; runs in Cloudflare Workers, Vercel Edge, Deno Deploy
• Tree-shakeable — "sideEffects": false with named exports per module; import only what you use
• 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 + 21 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