` | Something wraps `{children}` in a component that skips SSR, usually `next/dynamic({ ssr: false })` (e.g. the site's own lazy Providers) → 100% CSR. Never a plain `SiteKitLayout` on site-kit ≥3.0.2 | Keep the layout. Import that wrapper statically or mount it as a childless sibling. On <3.0.2, upgrade | `ssr.render` | | Build throws "runtime is not available in proxy" / codemod skips middleware.ts | Next 16's `proxy.ts` always runs on Node and rejects a `runtime` export; `middleware.ts` still accepts it | Remove the `runtime` export, then `npx sonor-setup codemod --write` moves the file to `proxy.ts` | `middleware.netlify` | | Invalid-key console spam; data features paused (401/403) | Stale/rotated key, or an env change wasn't redeployed | Put the current `sonor_` key in `.env.local` and redeploy | `key.valid` | | Deprecated `SiteKitProvider` in layout | 2.x integration | `npx sonor-setup codemod --only provider-to-layout --write` | `layout.sitekit` | | `@uptrademedia/site-kit` / `UPTRADE_*` remnants | pre-rebrand site | `npx sonor-setup codemod --only uptrade-to-sonor --write` | `package.installed` / `env.api-key` | | Hero present but LCP late | above-the-fold element is `opacity:0` + JS entrance-animated | Render hero fully static; gate reveal animations below the fold | — | ## Verifying (definition of done) ```bash npx sonor-setup verify --json # static health + key validity + SSR (from .next build) npx sonor-setup verify --url https://your-site.com --json # SSR check against a live/preview URL (strongest) ``` `verify` exits `0` only when the integration is genuinely green. If it exits non-zero, read `checks[]` — each red check carries a `fix` (and often a `fixCommand`), and `nextSteps[]` names what to run. Loop until green. --- # Layout — `@sonordev/site-kit/layout` RSC-compatible master layout that auto-composes all site-kit features. ## Usage ```tsx // app/layout.tsx import { SiteKitLayout } from '@sonordev/site-kit/layout' export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` Zero-config: reads `SONOR_API_KEY` from env, injects it into client modules automatically. ## Props ```ts interface SiteKitLayoutProps { children: React.ReactNode apiKey?: string // Defaults to SONOR_API_KEY env var apiUrl?: string // Defaults to SONOR_API_URL, then https://api.sonor.io projectId?: string // For chat routing (auto-resolved if omitted) analytics?: boolean | AnalyticsConfig // Default: true chat?: boolean | ChatLayoutConfig // Default: true (website chat; config = launcher placement) popups?: boolean // Default: true (Website → Popups & Banners) engage?: boolean | EngageConfig // Deprecated: false turns chat and popups off; an object configures the launcher signal?: boolean | SignalConfig // Default: false sitemapSync?: boolean // Default: false (build-time + server reconciler own this) fleet?: boolean // Default: true (once-per-session kit version heartbeat) defer?: boolean // Default: true (client modules wait for load + idle) favicon?: boolean // Default: true managedScripts?: boolean // Default: true debug?: boolean // Default: false showLlmsTxtFooterLink?: boolean // Default: false (prefer middleware discovery headers) speculation?: boolean | { mode?: 'prerender' | 'prefetch'; exclude?: string[] } // Default: false } ``` Module options live with each module: [Analytics](https://sonor.dev/site-kit/analytics) (`trackPageViews`, `excludePaths`, `site`, `allowInFrame`, `allowLocalhost`) [Website chat](https://sonor.dev/site-kit/chat) (`position`, `offsetBottom`, `zIndex`, `allowInFrame`) and [Popups and banners](https://sonor.dev/site-kit/popups). ## What It Composes **Server-side (RSC):** - `ManagedFavicon` — Sonor logo as `` tags - `ManagedScripts` — tracking pixels/analytics tags in `` and body-end positions - API preconnect/dns-prefetch hints **Client-side (lazy-loaded island):** - `AnalyticsProvider` — page views, scroll depth, heatmap clicks, Web Vitals - `SitePopups` — popups, banners and toasts - `SiteChat` — website chat (Echo) - `SignalBridge` — A/B experiments, behavior tracking (opt-in) - `SitemapSync` — parses `/sitemap.xml` and syncs to Sonor (opt-in) - `FleetHeartbeat` — reports the kit version and enabled modules once per session Since 4.0.0 none of these wrap your page. `{children}` renders first and every module mounts after it as a childless sibling, so `SiteKitLayout` never pushes a route to client rendering. Analytics, chat, popups, SitemapSync and the heartbeat also wait for window load + idle (or the first interaction) unless you pass `defer={false}`. `SignalBridge` isn't deferred, so experiment variants apply early. Visitor and session IDs come from a shared storage singleton rather than a provider. ## Note `SiteKitProvider` was **removed in 4.0.0**. It wrapped the whole tree client-side, which broke RSC. Migrate an older layout with `npx sonor-setup codemod --only provider-to-layout --write`. --- # Live updates Your pages stay cached, and when someone changes content in Sonor, the pages that use it refresh within seconds. It takes one route file: ```ts // app/api/seo-revalidate/route.ts export { POST } from '@sonordev/site-kit/revalidate' ``` `npx sonor-setup scaffold` writes it for you, and `npx sonor-setup doctor` tells you when it's missing. ## How it works Everything site-kit fetches from Sonor is cached, and pages built from those fetches are served from your host's CDN. When content changes in Sonor (managed copy, a page's title or description, an article, a portfolio item), Sonor sends this route the paths and cache tags that changed. The route checks the call was signed with your project's API key, then expires only those pages and tags. The next visitor gets the new version, and every other page stays cached. It's the same `SONOR_API_KEY` the rest of site-kit reads, so there's no extra secret to set. Sonor finds the route on its own: the first sitemap sync after a deploy registers `https://your-domain/api/seo-revalidate` and checks that it answers. Without the route, nothing breaks. Edits still show up, but only once each cached fetch ages out: about five minutes for managed copy, up to a day for metadata. ## Sites with a publication If your site publishes articles, tell the route where they live so the index and feeds refresh with each article: ```ts // app/api/seo-revalidate/route.ts import { createRevalidateRoute } from '@sonordev/site-kit/revalidate' export const POST = createRevalidateRoute({ publicationBasePath: '/insights' }) ``` | Option | What it does | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `publicationBasePath` | Where your articles live, e.g. `/insights`. The index and its RSS and Atom feeds refresh on every call. | | `extraPaths` | Local paths to refresh on every call, e.g. a hub page like `/work`. | | `extendPayload` | Map extra fields Sonor sends to more paths or tags. The result is validated again, so it can't widen what a caller may refresh. | | `secret` | The key calls are signed with. Defaults to `SONOR_API_KEY`, read on every call. | ## What Sonor sends A POST with `Authorization: Bearer ` and a JSON body: ```json { "paths": ["/services/roofing"], "tags": ["sonor-slots"] } ``` | Field | Meaning | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paths` | Local paths to regenerate. `/sitemap.xml`, `/llms.txt` and `/llms-full.txt` are always refreshed too. | | `tags` | Cache tags to expire. The ones Sonor uses are `SITE_CACHE_TAGS`: `sonor-slots` (managed copy), `seo` (metadata, schema, FAQs), `blog` (articles), `editorial-taxonomy` and `portfolio`. | | `revalidateAll` | Regenerate every page. | | `ping` | `{ "ping": true }` on its own regenerates nothing and answers `{ "ok": true, "ping": true, "version": "…" }`. Sonor uses it to confirm the route is installed. | The route refuses a bad key (401), a body over 16 KB (413) and any path that isn't a plain local path or any malformed tag (400). A refused call refreshes nothing. ## Checking it ```bash curl -s -X POST https://your-domain/api/seo-revalidate \ -H "Authorization: Bearer $SONOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ping":true}' ``` `{"ok":true,"ping":true,...}` means Sonor's edits will go live in seconds. A 404 means the route isn't deployed. A 401 means the key on the site doesn't match the project's key. --- # SEO: `@sonordev/site-kit/seo` Server Components and server helpers that render what you manage in the SEO module at [app.sonor.io](https://app.sonor.io): page metadata, JSON-LD, FAQs, internal links, content blocks, redirects and robots directives. The project comes from `SONOR_API_KEY`. Nothing in this module takes a project ID. A few option types and props still carry an optional `projectId` from older versions; it's ignored, so leave it out. ## Setup ```bash # .env.local SONOR_API_KEY=sonor_xxxxxxxx_xxxxx ``` That's the only variable you need. Keep it server-side, with no `NEXT_PUBLIC_` prefix. `SONOR_API_URL` is optional and defaults to `https://api.sonor.io`. If the key is missing, the server helpers throw: ``` @sonordev/seo: SONOR_API_KEY environment variable is required for server-side SEO functions ``` ## Entry points | Import | Runs on | Contains | | ------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `@sonordev/site-kit/seo` | Server only | Everything on this page except `registerLocalSitemap` | | `@sonordev/site-kit/seo/server` | Server only | The [data fetchers](#data-fetchers), `getManagedMetadata`, `getManagedMetadataWithAB`, `generateSitemap`, `registerLocalSitemap`, and the types | | `@sonordev/site-kit/seo/client` | Client | `SitemapSync` only | Both server entries import `server-only`, so importing either one from a Client Component fails the build. That's deliberate: it keeps the key out of the browser bundle. ## Page metadata ### `getManagedMetadata(options)` ```tsx // app/services/[slug]/page.tsx import { getManagedMetadata } from '@sonordev/site-kit/seo' export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) { const { slug } = await params return getManagedMetadata({ path: `/services/${slug}`, fallback: { title: 'Our Services', description: 'What we do and where we do it.', }, }) } ``` | Option | Type | Notes | | ----------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | `string` | Required. The page path as Sonor has it. | | `fallback` | `Metadata` | Fills any field Sonor has no managed value for. Used in full when the page isn't in Sonor at all. | | `overrides` | `Partial` | Applied last, so it wins over managed values. | | `favicon` | `'metadata' \| 'component'` | `'metadata'` (default) adds `icons` from the project logo. Pass `'component'` when your layout already renders the favicon, which `SiteKitLayout` does by default, so icons aren't emitted twice. | It returns a Next.js `Metadata` object with two extra flags, `_managed` and `_source`. Managed fields map like this: | Sonor field | Metadata field | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `managed_title` | `title` | | `managed_meta_description` | `description` | | `managed_keywords` | `keywords` | | `managed_robots` | `robots` | | `managed_canonical` | `alternates.canonical` | | `language_alternates` | `alternates.languages` | | `managed_og_title`, `managed_og_description`, `managed_og_image` | `openGraph` and `twitter` (`summary_large_image`), falling back to the title and description | When the page exists in Sonor but has neither a title nor a description, the call asks Signal to write them in the background and returns your fallback for now. The generated copy shows up once the cached response refreshes (see [Caching](#caching)). **Title templates.** The managed title comes back as a plain string, so a root-layout `title.template` still applies to it. If your managed titles already include the brand, you'll get it twice. Mark the title absolute: ```ts const metadata = await getManagedMetadata({ path: '/about' }) return typeof metadata.title === 'string' ? { ...metadata, title: { absolute: metadata.title } } : metadata ``` ### `withManagedMetadata(path, pageMetadata?)` Builds the `generateMetadata` function for you. Pick one of these forms: ```ts import { withManagedMetadata } from '@sonordev/site-kit/seo' // A fixed path export const generateMetadata = withManagedMetadata('/about') // A path built from params export const generateMetadata = withManagedMetadata( async ({ params }) => `/services/${(await params).slug}`, ) // Page-level values on top of Sonor's export const generateMetadata = withManagedMetadata('/about', async () => ({ title: 'About Us', })) ``` Whatever `pageMetadata` returns wins over Sonor's values. `openGraph` and `twitter` merge one level deep. It calls `getManagedMetadata` with the default `favicon: 'metadata'`. ### A/B-tested titles and descriptions `getManagedMetadataWithAB` works like `getManagedMetadata`, then swaps in the assigned variant of any running title or description test for that path. `getABVariant({ path, field, sessionId? })` does the same for one field (`'title' | 'description' | 'content'`) and returns `{ testId, variant, value }`, or `null` when nothing's running. ```ts import { cookies } from 'next/headers' import { getManagedMetadataWithAB } from '@sonordev/site-kit/seo' export async function generateMetadata() { const sessionId = (await cookies()).get('visitor_id')?.value return getManagedMetadataWithAB({ path: '/pricing', sessionId }) } ``` Pass a stable visitor ID your site already keeps. The kit doesn't set a cookie for this, and without one every request gets a random variant. Reading cookies makes the route dynamic, and each variant lookup records an impression. ## JSON-LD ### `` ```tsx import { ManagedSchema } from '@sonordev/site-kit/seo' export default function Page() { return ( <>

{/* ... */}

) } ``` It renders one `application/ld+json` script (an `@graph` when there's more than one node) that combines: - the schema Sonor has for the path, filtered by `includeTypes` / `excludeTypes` - the page's Signal-generated `managed_schema` - anything you pass in `additionalSchemas` - a `BreadcrumbList` built from the path, when there isn't one already and the project has a site URL (skipped on `/`) - a speakable `WebPage` or `Article` node, when `speakable`, `pageName` and `pageUrl` are all set Everything Sonor supplies (its schema rows, `managed_schema` and the entity graph) loses any template placeholder first. A node whose values are a template's unfilled slots is dropped: a URL on a reserved example domain (`example.com`), a name like "Example" or "Your Business Name", a placeholder phone such as `+1-000-000-0000`, a slot like `[Resident Name]` or `{plan.name}`, or an object that's only a note about what goes there. Its real siblings and parents stay, so an `FAQPage` keeps its questions when only its publisher was a placeholder, and the `BreadcrumbList` fallback still applies when a placeholder breadcrumb is dropped. Your `additionalSchemas` are never touched. The rule is `@sonordev/contracts/schema-placeholders`. | Prop | Default | Notes | | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `path` | | Required. | | `includeTypes` / `excludeTypes` | | Type allow and deny lists. `includeTypes` keeps Sonor schema rows by `schema_type`. `excludeTypes` drops a node of that `@type` wherever it sits in Sonor's schema: a whole row, an `@graph` member, or a nested value like `mainEntity`, and in `managed_schema` too. A row left empty is dropped. Your `additionalSchemas` are never filtered. | | `additionalSchemas` | `[]` | Extra nodes to merge in. | | `speakable` | | `true` for the default selectors (`h1`, `[data-speakable="true"]`, `.page-summary`, `.key-points`, `.aeo-block[data-speakable="true"]`), or `{ cssSelector }` / `{ xpath }`. | | `pageType` | `'WebPage'` | `'WebPage'` or `'Article'`, for the speakable node. | | `pageName`, `pageUrl` | | Required for the speakable node. | | `includeEntityGraph` | `true` | Meant to add nodes from Signal's entity graph. It adds nothing today; see [Entity graph](#entity-graph-and-ai-visibility). | It's wrapped in `Suspense`, so the fetch never holds up the rest of the page. The script streams in when it's ready. ### `` Renders the page's `managed_llm_schema` as a `WebPage` JSON-LD script marked `data-llm-optimized="true"`, linked to the site's `WebSite` node when the project has a site URL. It renders nothing when the page has no LLM schema, or when that schema is a template placeholder (see ``). ### Schema helpers - `createSchema(type, data)` returns `{ '@context': 'https://schema.org', '@type': type, ...data }`. - `createBreadcrumbSchema(baseUrl, path, labels?)` builds a `BreadcrumbList`. `labels` maps a path segment to its display name. - `createWebSiteOrganizationStub({ name, url, sameAs?, knowsAbout? })` returns a minimal `Organization` and `WebSite` pair with stable `@id`s. Only reach for it when Sonor isn't already emitting those nodes. Hand the result to `ManagedSchema` through `additionalSchemas`, so it's serialized and escaped in the same script as everything else. ## FAQs: `` ```tsx import { ManagedFAQ } from '@sonordev/site-kit/seo' ``` | Prop | Default | Notes | | --------------- | ---------- | --------------------------------------------------------------------------------------- | | `path` | | Required. | | `showTitle` | `true` | Renders the FAQ's title as an `

`. | | `includeSchema` | `true` | Emits `FAQPage` JSON-LD, but only when the FAQ is also set to include schema in Sonor. | | `renderItem` | | `(item, index) => ReactNode`, for your own markup. | | `className` | `'sk-faq'` | Wrapper class. | | `site` | | Sub-site host on a multi-site project. See [Multi-site projects](#multi-site-projects). | The default markup is native `

` / `

` with its own small `