Layout — @sonordev/site-kit/layout
RSC-compatible master layout that auto-composes all site-kit features.
The packaged layout keeps page content on the server and marks measurement and privacy modules as separate client islands. It supports Next.js webpack and Turbopack builds. The optional privacy notice stays lazy and loads only when the site's measurement configuration offers it.
Usage
// app/layout.tsx
import { SiteKitLayout } from '@sonordev/site-kit/layout'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<SiteKitLayout>{children}</SiteKitLayout>
</body>
</html>
)
}Zero-config: reads SONOR_API_KEY from env, injects it into client modules automatically.
Props
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)
privacyChoices?: boolean | PrivacyChoicesConfig // Default: true (Sonor's privacy choices, on a site with an enabled measurement configuration)
defer?: boolean // Default: true (client modules wait for load + idle)
favicon?: boolean // Default: true
managedScripts?: boolean // Default: true
debug?: boolean // Default: false
llmsDiscovery?: AiDiscoveryHeadersOptions | false // Default: false; static HTML links
showLlmsTxtFooterLink?: boolean // Default: false (prefer llmsDiscovery)
speculation?: boolean | { mode?: 'prerender' | 'prefetch'; exclude?: string[] } // Default: false
}Module options live with each module: Analytics (trackPageViews, excludePaths, site, allowInFrame, allowLocalhost) Website chat (position, offsetBottom, zIndex, allowInFrame) and Popups and banners.
privacyChoices takes false to turn the built-in notice off, or a PrivacyChoicesConfig to set any of privacyUrl (default /privacy), launcherLabel (default "Privacy choices") and promptMode (panel, the default, or dialog). A site that mounts ResonanceConsentPreferences itself replaces the built-in notice without setting anything. A site that connects its own consent manager passes privacyChoices={false} as well, so its consent manager is the only one asking. Resonance measurement has the details.
What It Composes
Server-side (RSC):
ManagedFavicon— Sonor logo as<link>tagsManagedScripts— tracking pixels/analytics tags in<head>and body-end positions- API preconnect/dns-prefetch hints
Client-side (lazy-loaded island):
AnalyticsProvider— page views, scroll depth, heatmap clicks, Web VitalsSitePopups— popups, banners and toastsSiteChat— website chat (Echo)SignalBridge— A/B experiments, behavior tracking (opt-in)SitemapSync— parses/sitemap.xmland syncs to Sonor (opt-in)FleetHeartbeat— reports the kit version and enabled modules once per session- Privacy choices: the consent notice and its Privacy choices button, on a site with an enabled measurement configuration and no consent manager of its own. While a configured site's configuration is stale or switched off and its visit measurement is running, the button stays and lets the visitor turn visit measurement off
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. The privacy notice waits for the visitor's first interaction, and a site that isn't offered it never downloads it. Visitor and session IDs come from a shared storage singleton rather than a provider.
Measurement without SiteKitLayout
A layout that isn't SiteKitLayout can mount the same Resonance runtime and the same privacy choices with SiteKitMeasurement from @sonordev/site-kit/measurement. @sonordev/agency-site-kit's AgencySiteKitLayout already does (agency-site-kit 0.14 and later), so a site on it needs no code. It's one source for both layouts: SiteKitLayout mounts the very same components, so the runtime, the default consent owner and the notice behave identically.
// app/layout.tsx (server component)
import { resolveClientCredential } from '@sonordev/site-kit/server'
import { SiteKitCredential } from '@sonordev/site-kit/client'
import { SiteKitMeasurement } from '@sonordev/site-kit/measurement'
export default async function RootLayout({ children }) {
const credential = await resolveClientCredential(process.env.SONOR_API_KEY ?? '', 'https://api.sonor.io')
return (
<html lang="en">
<body>
<SiteKitCredential apiKey={credential} />
{children}
<SiteKitMeasurement apiUrl="https://api.sonor.io" apiKey={credential} privacyChoices={{ privacyUrl: '/privacy' }} />
</body>
</html>
)
}It takes the minted apiKey and apiUrl, and optionally site (a multi-site host, resolved like the layout does when omitted), privacyChoices (as in the layout's prop) and chatPosition / chatOffsetBottom so the notice keeps clear of a chat launcher. It takes no children and renders after the page, so it never wraps or delays page content, and it defers its work to idle like the layout's other modules. Mount it once, in the layout that publishes the credential, and never beside SiteKitLayout or AgencySiteKitLayout: they already mount it, and a second runtime on the page is refused.
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.
AI discovery without changing preload headers
<SiteKitLayout llmsDiscovery={{ siteUrl: 'https://example.com', mcpServerCard: true }}>
{children}
</SiteKitLayout>This emits server-rendered <link rel="describedby"> for /llms.txt and an optional
<link rel="service-desc"> for the public MCP server card. React places them in
<head>. No client JavaScript, request reads, extra fetches, or changes to Next's
font and stylesheet preload headers are needed.
For a separate public layout, import AiDiscoveryLinks from
@sonordev/site-kit/layout and render it with the same props. Both forms accept
AiDiscoveryHeadersOptions: siteUrl, optional llmsPath, mcpServerCard
(true or a custom URL/path), languageAlternates, and includeTypeParameter.
They share URL construction and alternate filtering with buildAiDiscoveryHeaders.
Remove llmsDiscovery from createProxy and llmsTxtDiscoveryLink from
withSiteKitConfig when moving to HTML discovery. Those HTTP options remain
compatible but are deprecated: host adapters can replace Next's preload Link
header with the discovery value. Appending at the proxy cannot reliably merge
headers generated later by the framework.
Layout-level discovery links name only the configured public resources, even
on private child routes; they don't include the current URL, preview token, or
article content. Private preview cache, indexing, and reporting rules stay in
place. If private pages must contain no discovery tags at all, render
AiDiscoveryLinks in a public route-group layout instead of the root layout.
The layout publishes the current credential and first-party identity scope before child effects. Purpose checks stay synchronous while optional runtime work loads, so pending preferences and withdrawal don't create a collection window. Page content remains server-rendered independently of measurement.