@eight25-factory/seo-essentials

@eight25-factory/seo-essentials

Per-entry metadata into <head>, an XML sitemap that lists only published, translated, indexable pages, an environment-aware robots.txt, canonical URLs, and an og:type QA — for Next.js and Nuxt, with Contentful or Contentstack. Plus SKILLS.md, an instruction file that teaches an AI agent to keep every new page SEO-correct.

npm install               → the package detects the app and wires itself (postinstall)
Editor fills the SEO tab  → title, description, canonical, og:*, twitter:*, robots in <head>
Publishes a page          → it appears in that language's sitemap (/sitemaps/<locale>.xml, listed by /sitemap.xml)
Preview / staging deploy  → robots.txt says Disallow: /, every response says X-Robots-Tag: noindex
Production                → Allow, Sitemap: line, indexable

Install

One command in the project root. The package's postinstall runs init --yes --write for you: it detects Next or Nuxt, the CMS (from live-preview.config.mjs, CMS_PROVIDER, credential variable names or the SDK in package.json), asks the CMS for its locales when delivery credentials are in .env*, and writes the wiring:

npm install @eight25-factory/seo-essentials

What lands in the project (Next.js; Nuxt paths in docs/nuxt.md):

It also patches next.config.* (default export wrapped in withSeoEssentials, which adds X-Robots-Tag: noindex, nofollow outside production) and app/layout.tsx (export const metadata = rootMetadata({…})) when they have the create-next-app shape, and reports anything it left alone. Existing files are never overwritten.

Then, once, create the SEO fields in the CMS with the management token from .env and add demo values so there is something to look at:

npx seo-essentials provision --seed        # Contentful: `seo` content type + link on every page type
                                           # Contentstack: `seo` global field + reference on every page type

Prefer to see the plan first? npx seo-essentials init (no --write) prints every file; npx seo-essentials provision --dry-run prints every CMS change. pnpm and --ignore-scripts do not run dependency postinstalls: run npx seo-essentials init --write yourself.

Per-page metadata

Wired for you on Next: init patches every dynamic page route under app/ ([slug], [...slug], [[...slug]], with or without a [locale] segment) to export

// app/[[...slug]]/page.tsx — added by init
import { routeMetadata, type RouteParams } from "@/lib/seo/server";

export async function generateMetadata({
  params,
}: {
  params: Promise<RouteParams>;
}): Promise<Metadata> {
  return routeMetadata("/[[...slug]]", await params);
}

routeMetadata turns the route pattern and params into the page path and locale, fetches the entry whose URL field holds that path from the Delivery API (SEO group included, cached for five minutes), and emits title (templated), description, canonical, robots, Open Graph (with a valid og:type), Twitter and hreflang. The page query needs no change. A route that already had a generateMetadata keeps it: it is renamed generateMetadataWithoutSeo and the CMS metadata is layered over its result.

A route that loads its own entry can call pageMetadata(entry, { path, locale }) instead. It accepts the raw entry in any delivery shape (GraphQL object, REST { sys, fields }, Contentstack entry) and reads the SEO group by the conventional names — seo.metaTitle (Contentful) or seo.meta_title (Contentstack), plus legacy flat fields such as seoNoIndex — falling back to the page title and the site defaults.

Nuxt: usePageSeo(page, { path: route.path }) from the generated composable.

What it does

• Metadata in one call: title template, description, canonical, robots, og:*, twitter:*, hreflang + x-default, keywords; fallbacks are deliberate and reported as warnings.
• One sitemap per language: with more than one locale /sitemap.xml is a sitemap index listing /sitemaps/<locale>.xml for every language that has pages; each file carries that locale's URLs with xhtml:link alternates. Single-locale sites get one flat file.
• Sitemap that tells the truth: only published entries that answer 200 (each URL is checked, cached an hour; 404/410 and redirects drop out); per locale only when the entry is actually translated (Contentful: the entry stores its own value for translationField in that locale; Contentstack: the entry did not fall back); never noIndex or excludeFromSitemap pages; never duplicates; xhtml:link alternates grouped per entry; lastmod from the CMS; static paths appended; chunking helpers for > 50,000 URLs.
• Environment-aware robots: production (from SEO_ENVIRONMENT, then VERCEL_ENV, CONTEXT; never NODE_ENV) serves your policy plus the Sitemap: line; anything else serves Disallow: / and adds X-Robots-Tag: noindex, nofollow to every response.
• Canonicals with a policy: lowercase, no trailing slash, no query (configurable); entry-level override for deliberate duplicates; og:url and sitemap loc always equal the canonical.
• og:type QA: validateOgType classifies a stored value as valid, normalizable (Web page → website) or invalid; the helper renders the fix and reports it; npx seo-essentials audit <url> --sitemap fails a deployment on invalid values after a migration.
• CMS provisioning: provision creates the fields (idempotent) and, with --seed, demo values — published, with one page localized on request to demonstrate the translation rule.
• AI skill: SKILLS.md with rules, recipes, a verification protocol and a diagnosis table, installed by init and by npx seo-essentials install-skills.

What it deliberately does not do

• No runtime dependency on a CMS SDK or a framework. The package is pure functions; the Delivery API calls live in the generated lib/seo/pages.ts inside your app, where you can read and change them.
• No JSON-LD / structured data. That is content-type specific; add it in the page next to pageMetadata.
• No redirects or URL rewriting. Canonicals describe URLs; routing owns them.
• No NEXT_PUBLIC_* tokens. Only the Delivery token is read, on the server, by name.

Verify

With the app running:

npx seo-essentials audit http://localhost:3000            # one page's <head>
npx seo-essentials audit http://localhost:3000 --sitemap  # robots.txt + sitemap + every listed page
npx seo-essentials check-env                              # which variable names are set (never values)

Supported integrations

Documentation

Requirements

Node 22 or newer. No runtime dependencies.