better-seo.js

A programmable SEO engine for modern apps. Not just tags — structured discoverability. One source of truth for metadata, Open Graph, Twitter cards, and JSON-LD. Map to Next.js Metadata, React Helmet, or plain tags — without five parallel sources of truth.

0runtime deps
~5KBgzip
354unit tests
94%+core coverage
7packages
60sto first SEO

The Problem

Approach Problem
next-seo Static config, no system thinking, zero feedback loop
React Helmet Manual everything, no abstraction, no structured data
Next.js Metadata Low-level primitive, no schema system, rendering only

Result: Developers have helpers, not infrastructure. No unified model. No extensibility.

The Solution

One Source of Truth

Describe SEO once → render to Next.js Metadata, React Helmet, or vanilla tags. No drift between channels.

Core

JSON-LD First-Class

Structured data isn't an addon — it's built in. 8 schema.org helpers + custom escape hatch. HTML-safe serialization.

Security

Zero-Dependency Core

@better-seo/core ships with zero runtime npm dependencies. Edge-safe, Worker-safe, Browser-safe.

~5KB gzip

Framework Adapters

Next.js (App + Pages Router), React/Helmet. One contract — Remix, Astro, Nuxt planned.

P0: Next.js

Rules & Plugins

Glob-based route rules. 4 plugin hooks: beforeMerge, afterMerge, onRenderTags, extendChannels.

Scale

CLI + Asset Pipeline

OG image generation (Satori), favicon/icon pipeline, splash screens, crawl artifacts (robots, sitemap, RSS/Atom, llms.txt).

Automation

The "Voilà" Principle

Time-to-value = everything. If a dev can't go from install → working SEO in under 60 seconds, they'll leave. 
npm install @better-seo/core @better-seo/next
// app/page.tsx (Next.js App Router)
import { seo } from "@better-seo/next"

export const metadata = seo({ title: "Home" })

It must just work. No config ceremony. No mental overhead.

3 Levels of Depth (Same API)

Level Code Use Case
🟢 Lazy seo({ title: "…" }) Defaults from env + package.json (Node)
🟠 Normal seo({ title: "Dashboard" }) Override title, keep defaults
🔴 Power seo({ meta, openGraph, schema }) Full control over every channel

What Ships (v0.0.2)

@better-seo/core

createSEO, mergeSEO, 8 schema helpers, serializeJSONLD, validateSEO, renderTags, rules engine, plugin system, adapter registry, createSEOContext, fromNextSeo, fromContent, defineSEO

0 deps · 18 features

@better-seo/next

seo(), prepareNextSeo, withSEO, seoLayout, seoPage, seoRoute, toNextMetadata, NextJsonLd — full App Router support

10 features

@better-seo/react

BetterSEOHelmet, toHelmetProps, SEOProvider, useSEO — React SPA / Vite integration

Wave 5

@better-seo/assets

generateOG (Satori), generateIcons (Sharp), generateSplash, buildWebAppManifest, ogPaletteFromTokens

5 features

@better-seo/cli

Interactive TUI, og, icons, splash, init, doctor, migrate, snapshot, preview, analyze, scan, fix, crawl (robots/sitemap/rss/atom/llms/sitemap-index), template (list/print/preview)

17 commands

@better-seo/crawl

renderRobotsTxt, renderSitemapXml, renderSitemapIndexXml, renderRssXml, renderAtomFeed, renderLlmsTxt

Wave 12

@better-seo/compiler

fromMdx — gray-matter frontmatter + body → SEOInput (fromContent delegate)

Wave 7

Quick Links

Get Started (~60s)

Install, configure, and have working SEO on your first page.

→ getting-started

Concepts

The SEO object, pipeline, merge strategy, serialization, adapters.

→ concepts

API Reference

createSEO, mergeSEO, serializeJSONLD, schema helpers, validateSEO, plugins.

→ api

Recipes

Layout merge, route rules, OG, icons, MDX, React SPA, sitemap/robots.

→ recipes

CLI Commands

og, icons, init, doctor, scan, fix, snapshot, preview, analyze, crawl, template.

→ cli

Compare

vs next-seo, vs Next.js Metadata, vs react-helmet — why better-seo.js wins.

→ compare

Architecture at a Glance

Your App (Next.js / React / Remix / …)
  → @better-seo/<adapter>   (framework output)
       → @better-seo/core   (0 deps: model + merge + serialize + plugins)

Optional:
  @better-seo/assets   → OG images, icons, splash
  @better-seo/cli      → init, og, icons, doctor, scan, fix, crawl
  @better-seo/crawl    → robots.txt, sitemap.xml, RSS/Atom, llms.txt
  @better-seo/compiler → fromMdx (frontmatter + body → SEO)

Ecosystem