docs
    site-kit: Layout
    v8.13.4.md

    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> tags
    • ManagedScripts — 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 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
    • 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.