How to Score Your Content for Readability and SEO with TypeScript

#javascript #typescript #webdev #tutorial

Ever wonder why some blog posts get 10x more engagement than others? The secret often isn't the topic — it's readability. Content teams at places like the NYT and gov.uk actively measure reading grade levels to make sure their writing actually reaches people.

But most readability tools are online-only paste-boxes. You can't plug them into a CI pipeline, run them against your docs folder, or import them into a content workflow. I built textlens to fix that: a zero-dependency TypeScript toolkit that scores readability, sentiment, SEO, and more — as a library or CLI.

This tutorial shows you how to use it.

The Problem: Content Quality Is Measurable

"Good writing" sounds subjective, but it's not — at least not entirely. Readability formulas have been studied since the 1940s. The U.S. military commissioned the Flesch Reading Ease formula to make training manuals more accessible. The Gunning Fog Index was created by a newspaper consultant to cut corporate jargon.

These formulas work by measuring concrete things: word length, sentence length, syllable count. They output a grade level — the number of years of education needed to understand the text.

The problem for developers? Most tools that use these formulas are either:

Online-only — paste your text into a web form, no API
Heavy on dependencies — pulling in NLP libraries for a simple word count
Single-formula — giving you one score instead of a consensus

What we really need is something we can npm install and run in a script.

Quick Start

Install textlens:

npm install textlens

Run a full analysis on any text:

import { analyze } from 'textlens';

const text = `Search engine optimization is not just about keywords
anymore. Modern search engines evaluate content quality, readability,
and user engagement signals. If your article is difficult to read,
visitors will bounce quickly.`;

const result = analyze(text);

console.log(`Reading time: ${result.readingTime.minutes} min`);
console.log(`Grade level: ${result.readability.consensusGrade}`);
console.log(`Sentiment: ${result.sentiment.label}`);
console.log(`Top keyword: ${result.keywords[0].word}`);

The analyze() function returns everything at once: statistics, readability scores across 8 formulas, reading time, sentiment, keyword extraction, and an extractive summary. Each property is also available as a standalone function if you only need one thing.

Deep Dive: Readability Formulas

textlens implements 8 readability formulas and computes a consensus grade from 7 of them:

Formula	What It Measures
Flesch Reading Ease	Scored 0-100 (higher = easier). Based on sentence length and syllables per word.
Flesch-Kincaid Grade	U.S. grade level. The most widely used formula.
Gunning Fog Index	Grade level with emphasis on "complex words" (3+ syllables).
Coleman-Liau Index	Uses character count instead of syllables — more reliable for short text.
SMOG Index	"Simple Measure of Gobbledygook." Estimates years of education needed.
Automated Readability Index	Character-based, originally designed for typewriters.
Dale-Chall	Compares against a list of 3,000 words familiar to 4th graders.
Linsear Write	Weights "easy" vs "hard" words. Developed for the U.S. Air Force.

The consensusGrade averages across grade-level formulas, giving you a single number that's more reliable than any individual formula.

import { readability } from 'textlens';

const scores = readability(text);

console.log(`Flesch Ease: ${scores.fleschReadingEase.score} (${scores.fleschReadingEase.interpretation})`);
console.log(`Flesch-Kincaid: Grade ${scores.fleschKincaidGrade.grade}`);
console.log(`Gunning Fog: Grade ${scores.gunningFogIndex.grade}`);
console.log(`Consensus: Grade ${scores.consensusGrade}`);

What grade level should you target?

Audience	Target Grade	Flesch Ease
General public	6-8	60-70
High school students	9-12	50-60
Technical documentation	10-14	30-50
Academic papers	14+	0-30

Most successful blog posts land between grades 6 and 9. If your consensus grade is above 12, consider shorter sentences and simpler word choices.

Practical: SEO Content Scoring

textlens includes an seoScore() function that evaluates content on four dimensions:

import { seoScore } from 'textlens';

const result = seoScore(text, { targetKeyword: 'readability' });

console.log(`Score: ${result.score}/100 (${result.grade})`);
console.log('Issues:', result.issues);
console.log('Suggestions:', result.suggestions);
console.log('Breakdown:', result.details);
// => { readabilityScore, contentLengthScore, keywordScore, sentenceVarietyScore }
// Each sub-score is out of 25 points

The four sub-scores (each out of 25) measure:

Readability — Is your grade level appropriate for a general audience?
Content length — 300-2500 words is the sweet spot.
Keyword usage — Is your target keyword present at 1-3% density?
Sentence variety — Do you mix short and long sentences?

Each comes with actionable suggestions. "Simplify language to target grade 7" is more useful than a raw number.

CLI for Quick Checks

Don't want to write code? Use the CLI directly:

npx textlens article.md

This prints a formatted report with reading time, readability scores, and consensus grade.

For scripting, use the --json flag:

npx textlens article.md --json | jq '.readability.consensusGrade'

For the full analysis including sentiment, keywords, density, SEO, and summary:

npx textlens article.md --all

You can also pipe from stdin:

cat README.md | npx textlens

Bonus: Add to Your CI Pipeline

Here's a GitHub Actions step that fails if your docs exceed grade 12:

- name: Check docs readability
  run: |
    GRADE=$(npx textlens docs/guide.md --json | jq '.readability.consensusGrade')
    if (( $(echo "$GRADE > 12" | bc -l) )); then
      echo "Readability too low: grade $GRADE (target: <= 12)"
      exit 1
    fi

This ensures documentation stays accessible as your project grows. You could also check README files, blog post drafts, or API docs.

Wrapping Up

textlens gives you readability scoring (8 formulas with consensus), sentiment analysis, keyword extraction, SEO scoring, and more — all with zero runtime dependencies. It works as a TypeScript/JavaScript library and as a CLI tool.