docs
    site-kit: For coding agents
    v8.13.4.md

    Integrating a site with Sonor: agent guide

    You installed @sonordev/site-kit. This file tells a coding agent how to wire a Next.js site to Sonor correctly and prove it works, with no web access needed. Editing site-kit itself? See CONTRIBUTING.md.

    For the full machine-readable contract (modules, env, blessed patterns, failure modes, exit codes) run:

    npx sonor-setup manifest --json

    Everything below is also in that manifest. This file is the human-skimmable version.

    North star

    Take a bare Next.js repo → a fully wired, verified-green Sonor site. The signal that you're done is verify exiting 0, not "the command ran."

    Canonical sequence

    npx sonor-setup manifest --json                              # discover the package
    npx sonor-setup init --api-key "$SONOR_API_KEY" --yes --json # wire layout + .env.local + postbuild
    npx sonor-setup scaffold --yes --json                        # sitemap, robots, llms, proxy
    npx sonor-setup mcp --yes --json                             # agent tools: MCP endpoint, card, relay (optional)
    # Existing 2.x-6.x site? migrate deterministically:
    npx sonor-setup codemod --check --json                       # exit 1 ⇒ work pending
    npx sonor-setup codemod --write --json                       # apply (idempotent, minimal diffs)
    # Site with commerce or articles? Move imports to their companion packages:
    npx sonor-setup codemod --only site-kit-8 --write --json     # swaps the package name in its imports
    pnpm install                                                 # the codemod edits package.json, not node_modules (or npm / yarn)
    next build                                                   # you run the build
    npx sonor-setup verify --json                                # exit 0 === done

    The machine contract

    • Every agent-native command supports --json and prints exactly ONE JSON envelope to stdout (all human logs go to stderr). Parse stdout; branch on exitCode / ok / checks.
    • Exit codes: 0 OK · 1 FAILED (result is red, fix the code) · 2 USAGE (bad invocation) · 3 CONFIG (missing input; the error names the flag) · 4 NETWORK (API/key) · 5 INTERNAL.
    • Never interactive under --json, --yes, or a non-TTY. A command that needs input exits 3 with an actionable fix instead of hanging.
    • Each checks[] finding has a stable id, a fix, and often a fixCommand you can run directly.

    The one env var

    The only variable a site needs is:

    SONOR_API_KEY=sonor_1a2b3c4d_...   # server-side only, NO NEXT_PUBLIC_ prefix

    SiteKitLayout reads it server-side and derives the project id + all client config. Never add NEXT_PUBLIC_SONOR_API_KEY, UPTRADE_API_KEY, NEXT_PUBLIC_UPTRADE_API_KEY, or SONOR_PROJECT_ID. Pre-rebrand keys and variables are fully deprecated. Key format: sonor_{project-uuid-first8}_{secret}.

    Blessed patterns

    Root layout: SiteKitLayout (a server component), wrap {children}:

    import { SiteKitLayout } from '@sonordev/site-kit/layout'
    
    export default function RootLayout({ children }) {
      return (
        <html lang="en">
          <body>
            <SiteKitLayout>{children}</SiteKitLayout>
          </body>
        </html>
      )
    }

    Use SiteKitLayout, never the deprecated SiteKitProvider (it forces the whole tree client-side and breaks RSC/SSR). codemod migrates it for you.

    Analytics is already a deferred, childless sibling. Don't wrap {children}, and don't hand-roll it. Since 3.0.2, SiteKitLayout renders {children} first and mounts analytics, chat, popups and the fleet heartbeat after it, deferred to window load + idle (or the first interaction). 4.0.0 removed the last wrappers. So the plain layout above is the whole pattern: configure analytics with analytics={{ ... }}, and track custom events with the standalone trackEvent / trackConversion from @sonordev/site-kit/analytics (no provider needed; useAnalytics() throws outside one).

    What still de-opts a statically prerenderable route to 100% client rendering (the hero paints only after hydration; mobile LCP tanks) is a component you wrap around {children} that skips server rendering, usually next/dynamic({ ssr: false }). The old SiteKitLayout analytics={false} plus a hand-rolled deferred sibling was the workaround for site-kit <3.0.2. On those installs, upgrade.

    Agent tools: the built-in Sonor MCP server (7.0). Don't hand-write business-info, FAQ or review tools; npx sonor-setup mcp wires sonorMcpServer from @sonordev/site-kit/mcp/sonor, and a site's own tools go in its tools array. send_inquiry needs the person's go-ahead (person_confirmed: true) and a form with "Agent inquiries" on in Sonor. Pass onToolCall: reportToolCallsToSonor() to createMcpHandler so Sonor sees which agents called. A site that already runs its own MCP server is a custom implementation: sonor-setup mcp leaves it alone, and so should you; add reporting to it rather than replacing it.

    Imports: from a module's entry (@sonordev/site-kit/sync, /website/images, /seo/llms), never the root, which is types-only. The package is ESM only.

    Commerce and memberships (8.0). Commerce isn't in site-kit any more, and memberships is new and ships only in commerce-kit. Products, services, events, checkout and memberships are @sonordev/commerce-kit, which builds on site-kit and releases on its own. Install it beside site-kit and import from @sonordev/commerce-kit/commerce, /commerce/server, /memberships or /memberships/server; its root entry is types-only (CommerceOffering and the other commerce types). The old site-kit commerce entries are gone, so don't import commerce from site-kit; npx sonor-setup manifest --json lists every moved subpath under relocated, the types the root used to export under relocatedTypes, and what was retired for good under removed. A 7.x site that sells moves with npx sonor-setup codemod --only site-kit-8 --write (the guide is Moving a site to site-kit 8). The opt-in list_offerings agent tool needs a reader since 8.0: sonorMcpServer({ businessName, offerings: { path: '/shop', read: getOfferingsResult } }), with getOfferingsResult from @sonordev/commerce-kit/commerce/server.

    Articles and publications live in @sonordev/press-kit (Site Kit 8.3+ peer). Import client components from /articles, server data from /articles/server, and RSC components from /articles/server-ui. Keep SiteKitLayout from Site Kit. Legacy @sonordev/site-kit/articles* imports stay compatible in 8.x; migrate with npx sonor-setup codemod --only site-kit-8 --write, install, and build. The codemod adds Press Kit and raises the Site Kit dependency to 8.3. Site MCP uses the same readers as the pages: articles: { path: '/news', readMany: getAllArticles, readOne: getArticle }, with both readers from @sonordev/press-kit/articles/server. Use articles: false for a site without articles. New sonor-setup mcp scaffolds this wiring; --no-articles doesn't need Press Kit. See Press Kit migration.

    Building a package on top of site-kit (a kit, as commerce-kit is)? Take the browser transport from @sonordev/site-kit/runtime (sonorFetch, getClientApiConfig) and server data from @sonordev/site-kit/server, and don't read window.__SITE_KIT_* or call fetch on the Sonor API yourself. List site-kit as a peer dependency. See Building a kit.

    Common failure modes → the check that catches it

    SymptomCauseFixdoctor/verify check
    Mobile LCP ~4s; server HTML is an empty shell + self.__next_f flight data, no <section>/<h1>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.2Keep the layout. Import that wrapper statically or mount it as a childless sibling. On <3.0.2, upgradessr.render
    Build throws "runtime is not available in proxy" / codemod skips middleware.tsNext 16's proxy.ts always runs on Node and rejects a runtime export; middleware.ts still accepts itRemove the runtime export, then npx sonor-setup codemod --write moves the file to proxy.tsmiddleware.netlify
    Invalid-key console spam; data features paused (401/403)Stale/rotated key, or an env change wasn't redeployedPut the current sonor_ key in .env.local and redeploykey.valid
    Deprecated SiteKitProvider in layout2.x integrationnpx sonor-setup codemod --only provider-to-layout --writelayout.sitekit
    @uptrademedia/site-kit / UPTRADE_* remnantspre-rebrand sitenpx sonor-setup codemod --only uptrade-to-sonor --writepackage.installed / env.api-key
    Hero present but LCP lateabove-the-fold element is opacity:0 + JS entrance-animatedRender hero fully static; gate reveal animations below the foldnone
    Build can't resolve a site-kit commerce path (Can't resolve '@sonordev/site-kit/commerce', or Package subpath './commerce' is not defined by "exports")The site is on site-kit 8, where commerce moved to @sonordev/commerce-kitnpm install @sonordev/commerce-kit, then npx sonor-setup codemod --only site-kit-8 --write, then buildnone

    Verifying (definition of done)

    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.