@geenius/seo

Typed SEO metadata, SSR-safe head tags, JSON-LD, canonical URLs, sitemaps, robots, editorial scoring, and admin/preview UI for Geenius applications.

Public consumer documentation: /.docs/DOCS/PACKAGES/SEO.md. PRD: /.docs/PRDS/packages/PACKAGE_SEO_PRD.md.

Quick start

pnpm add @geenius/seo

import { createPageMeta, createSEOConfig } from '@geenius/seo'
import { SeoProvider, SEOHead, SEOPreview } from '@geenius/seo/react'

const config = createSEOConfig()
  .withSiteName('Acme')
  .withSiteUrl('https://acme.com')
  .withTitleTemplate('%s | Acme')
  .build()

const meta = createPageMeta(config, 'Pricing', 'Compare plans.')
  .withCanonical('https://acme.com/pricing')
  .withUpdatedAt('2026-05-13T00:00:00.000Z')
  .build()

export function PricingRoute() {
  return (
    <SeoProvider config={config}>
      <SEOHead meta={meta} />
      <SEOPreview meta={meta} />
    </SeoProvider>
  )
}

For the Vanilla CSS variants, also import the public stylesheet:

import '@geenius/seo/react-css/styles.css'
// or
import '@geenius/seo/solidjs-css/styles.css'

SolidJS consumers use the same root builders with the SolidJS subpath:

import { createPageMeta, createSEOConfig } from '@geenius/seo'
import { SeoProvider, SEOHead, SEOPreview } from '@geenius/seo/solidjs'

Public surface

• Root @geenius/seo — framework-agnostic builders, JSON-LD helpers, sitemap/robots, scoring, errors, types, and adapter-shaped persistence helpers (listSeoPages, upsertSeoPage, listSeoAnalytics, listSeoAuditSnapshots, upsertSeoAuditSnapshot).
• React subpaths — @geenius/seo/react and @geenius/seo/react-css. Each exports SeoProvider, hooks, components (SEOHead, JsonLd, MetaEditor, SEOPreview, SEOScoreCard, SitemapViewer), and pages (SEOAdminPage, SEOAnalyticsPage).
• SolidJS subpaths — @geenius/seo/solidjs and @geenius/seo/solidjs-css. Each exports SeoProvider, reactive primitives (createSEO, createSEOScore, createSitemap, createStructuredData, createCanonical, createSEOAdmin), components, and pages.

The current scoped package surface ships the root shared API plus react, react-css, solidjs, and solidjs-css public subpaths. Deferred variants remain marked out of scope in variants.json and are excluded from build, type-check, and test matrices.

Variants

| Subpath | Framework | Styling | Status | |---|---|---|---| | @geenius/seo/react | React DOM | Tailwind/token classes | In scope | | @geenius/seo/react-css | React DOM | Vanilla CSS BEM | In scope | | @geenius/seo/solidjs | SolidJS | Tailwind/token classes | In scope | | @geenius/seo/solidjs-css | SolidJS | Vanilla CSS BEM | In scope |

Deferred variants are not exported in this run: react-shadcn, react-mui, react-ant, react-chakra, react-mantine, react-heroui, react-daisyui, react-native, solidjs-ark, solidjs-kobalte, and solidjs-solidui. react-mantine and react-native have dormant source scaffolds marked inScope: false; they are absent from root files, exports, and typesVersions.

Persistence

SEO is variant-free for DB: any UI variant accepts a DbAdapter from @geenius/db via <SeoProvider db={...}>. Without a db, the provider is read-only and falls back to config.pages.

import { createMemoryDbAdapter } from '@geenius/db/memory'
import { SeoProvider } from '@geenius/seo/react'

const db = createMemoryDbAdapter()
<SeoProvider config={config} db={db}>{children}</SeoProvider>

See the consumer docs for Convex, Neon, Cloudflare KV, and memory recipes.

Ecosystem dependencies

The in-scope package source consumes @geenius/db through adapter-shaped persistence contracts. Shared SEO helpers consume @geenius/i18n for locale-aware alternates and fallback translation helpers, and @geenius/errors for typed SEO errors. The shipped UI variants consume the matching @geenius/ui primitives where admin controls need the Geenius component contract. Package Storybook apps consume @geenius/storybook helpers for review infrastructure.

Contributing tests

Variant-aware scripts read variants.json; add a new implemented variant there before wiring package scripts, Storybook, Playwright, coverage, or size budgets. The root fanout commands delegate to @geenius/release-toolkit, which includes the variant automatically when its packages/<variant>/ directory exists and the variant is in scope.

Useful local checks:

• pnpm type-check
• pnpm build
• pnpm test
• pnpm test:gauntlet
• pnpm test:all
• pnpm test:visual -- --update-snapshots

The current implementation surface is the root shared API plus react, react-css, solidjs, and solidjs-css; all deferred variants stay listed as planned work with inScope: false in variants.json.