@power-seo/readability

@power-seo/readability

Multi-algorithm readability scoring for TypeScript — Flesch Reading Ease, Flesch-Kincaid, Gunning Fog, Coleman-Liau, and ARI in one unified API with actionable status labels.

@power-seo/readability runs five industry-standard readability formulas against any text or HTML string and returns structured, typed score objects with numeric values and 'good' / 'improvement' / 'error' status labels — comparable to the readability scoring panels in Yoast SEO or Hemingway App, but as a standalone TypeScript library. Run it server-side in a CMS pipeline, client-side in a React editor, or inside a CI content quality gate. All five algorithm functions are independently importable and tree-shakeable.

Zero runtime dependencies — pure TypeScript, no NLP libraries, works in any JavaScript environment.

Why @power-seo/readability?

	Without	With
Algorithm coverage	❌ One-off Flesch score, no other algorithms	✅ Five algorithms in one call — Flesch, Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI
Status labels	❌ Raw numbers only — interpret thresholds manually	✅ 'good' / 'improvement' / 'error' per score with a human message
HTML input	❌ Must strip HTML before calling	✅ HTML tags stripped automatically
Composite status	❌ No aggregate result	✅ overall.status combines all five algorithms
TypeScript	❌ Untyped result objects	✅ Full type inference for all inputs and outputs
CI integration	❌ Manual threshold checks	✅ overall.status === 'error' fails builds
Framework support	❌ Browser-only or Node-only tools	✅ Works in Next.js, Remix, Gatsby, Vite, Edge, browser

Features

• Flesch Reading Ease — 0–100 score; higher = easier; target 60–70 for most web content
• Flesch-Kincaid Grade Level — maps content to US school grade levels (e.g. 8.0 = 8th grade)
• Gunning Fog Index — grade-level estimate based on complex word (3+ syllable) density
• Coleman-Liau Index — character-based formula; no syllable counting required
• Automated Readability Index (ARI) — grade estimate from character and word counts
• Unified analyzeReadability() API — run all five algorithms in a single call with composite status
• Text statistics — sentence count, word count, syllable count, character count, avg sentence length
• Status labels — each score maps to 'good' / 'improvement' / 'error' with a human message
• HTML stripping — HTML tags are removed automatically before scoring; no preprocessing required
• Zero runtime dependencies — pure TypeScript; no NLP libraries
• Tree-shakeable — import only the algorithms you need; "sideEffects": false
• Type-safe API — TypeScript-first with full type inference for all inputs and outputs
• Framework-agnostic — works in Node.js, browser, Next.js, Remix, Gatsby, Vite, Edge

Comparison

Feature	@power-seo/readability	text-readability	readability-scores	flesch
Flesch Reading Ease	✅	✅	✅	✅
Flesch-Kincaid Grade	✅	✅	✅	❌
Gunning Fog Index	✅	✅	✅	❌
Coleman-Liau Index	✅	✅	✅	❌
Automated Readability Index	✅	✅	✅	❌
Status labels (good/improvement/error)	✅	❌	❌	❌
Unified multi-algorithm API	✅	❌	❌	❌
Composite overall status	✅	❌	❌	❌
HTML auto-stripping	✅	❌	❌	❌
TypeScript-first with full types	✅	❌	❌	❌
Zero runtime dependencies	✅	✅	✅	✅
Tree-shakeable individual functions	✅	❌	❌	✅

Installation

npm install @power-seo/readability

yarn add @power-seo/readability

pnpm add @power-seo/readability

Quick Start

import { analyzeReadability } from '@power-seo/readability';

const result = analyzeReadability({
  text: 'Search engine optimization is the practice of improving web pages to rank higher in search results. Good content uses clear sentences and relevant keywords.',
});

console.log(result.fleschReadingEase.score); // e.g. 58.4
console.log(result.fleschKincaidGrade.score); // e.g. 10.2
console.log(result.overall.status); // 'improvement'
console.log(result.overall.message); // 'Content may be difficult for some readers...'

Status thresholds (per score):

• good — score is within the optimal range for web content
• improvement — score is outside the ideal range; consider simplifying
• error — score indicates content is too complex for most web readers

Usage

Running All Algorithms at Once

analyzeReadability() runs all five algorithms and returns a composite overall status:

import { analyzeReadability } from '@power-seo/readability';

const result = analyzeReadability({
  text: '<h1>React SEO Best Practices</h1><p>Search engine optimization for React applications requires attention to meta tags, structured data, and performance metrics.</p>',
});

// result.fleschReadingEase    → AlgorithmScore
// result.fleschKincaidGrade   → AlgorithmScore
// result.gunningFog           → AlgorithmScore
// result.colemanLiau          → AlgorithmScore
// result.automatedReadability → AlgorithmScore
// result.stats                → TextStatistics
// result.overall              → AnalysisResult

Running Individual Algorithms

Import individual algorithm functions for targeted scoring in performance-sensitive paths. All accept TextStatistics and return AlgorithmScore. Use getTextStatistics from @power-seo/core to compute statistics:

import { fleschReadingEase, gunningFog } from '@power-seo/readability';
import { getTextStatistics } from '@power-seo/core';

const stats = getTextStatistics('Your plain text here.');
const ease = fleschReadingEase(stats);
const fog = gunningFog(stats);

console.log(ease.score); // 0–100 (higher = easier)
console.log(fog.score); // grade level
console.log(ease.status); // 'good' | 'improvement' | 'error'

Inside a CI Content Quality Gate

Fail builds when content readability is too low:

import { analyzeReadability } from '@power-seo/readability';

const result = analyzeReadability({ text: pageContent });

if (result.overall.status === 'error') {
  console.error('Readability check failed:', result.overall.message);
  console.error('Flesch Reading Ease:', result.fleschReadingEase.score);
  console.error('Gunning Fog Index:', result.gunningFog.score);
  process.exit(1);
}

Score Interpretation

Flesch Reading Ease	Difficulty	Typical Audience
90–100	Very Easy	5th grade
70–90	Easy	6th grade
60–70	Standard	7th–8th grade — ideal for most web content
50–60	Fairly Difficult	High school
30–50	Difficult	College
0–30	Very Difficult	Academic / professional

Grade Level Score	Status
≤ 8	'good' — accessible to general audiences
9–12	'improvement' — consider simplifying
> 12	'error' — too complex for most web readers

API Reference

analyzeReadability(input)

function analyzeReadability(input: ReadabilityInput): ReadabilityOutput;

ReadabilityInput

Prop	Type	Description
text	string	Plain text or HTML string (HTML tags stripped automatically)

ReadabilityOutput

Field	Type	Description
fleschReadingEase	AlgorithmScore	Flesch Reading Ease result
fleschKincaidGrade	AlgorithmScore	Flesch-Kincaid Grade Level result
gunningFog	AlgorithmScore	Gunning Fog Index result
colemanLiau	AlgorithmScore	Coleman-Liau Index result
automatedReadability	AlgorithmScore	Automated Readability Index result
stats	TextStatistics	Underlying text statistics
overall	AnalysisResult	Composite status and message

Individual Algorithm Functions

All accept TextStatistics and return AlgorithmScore:

function fleschReadingEase(stats: TextStatistics): AlgorithmScore;
function fleschKincaidGrade(stats: TextStatistics): AlgorithmScore;
function gunningFog(stats: TextStatistics): AlgorithmScore;
function colemanLiau(stats: TextStatistics): AlgorithmScore;
function automatedReadability(stats: TextStatistics): AlgorithmScore;

Text Statistics

To compute text statistics for use with individual algorithm functions, use getTextStatistics() from @power-seo/core:

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

function getTextStatistics(text: string): TextStatistics;

Returns raw statistics used by all algorithm functions. Input can be plain text or HTML (HTML tags are stripped automatically).

Types

Type	Description
ReadabilityInput	{ text: string }
ReadabilityOutput	Full result with all five algorithm scores + stats + overall
TextStatistics	{ sentences: number; words: number; syllables: number; characters: number; avgWordsPerSentence: number }
AlgorithmScore	{ score: number; status: AnalysisStatus; message: string }
AnalysisStatus	'good' | 'improvement' | 'error'
AnalysisResult	{ status: AnalysisStatus; message: string }

Use Cases

• Programmatic SEO pages — score thousands of auto-generated pages at build time
• CMS editorial dashboards — show live readability scores as editors write content
• SaaS marketing sites — gate content publication behind a minimum readability threshold
• Blog and content pipelines — CI check that fails when content is too complex
• E-commerce product descriptions — ensure product copy is accessible to your target audience
• Educational platforms — match content reading level to target student grade
• Next.js / Remix apps — score content server-side per route and expose scores in admin dashboards

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero runtime dependencies — pure computation; no NLP libraries, no external tools
• Framework-agnostic — works in any JavaScript environment with no DOM requirement
• 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
• HTML stripping — uses a string-based tag removal loop (no regex ReDoS risk)
• Tree-shakeable — "sideEffects": false with named exports per algorithm function
• 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