@sonordev/site-kit
All-in-one integration kit for Sonor-powered Next.js sites. One shared foundation and one env var for the modules a site needs: SEO, Analytics, Forms, Website chat, Popups, GEO/AEO, Booking, Reputation, A/B Testing, and more, all managed from the Sonor dashboard at app.sonor.io. Products, events and memberships come from the companion package @sonordev/commerce-kit, which builds on site-kit.
Articles, publications and Broadcast-powered editorial artwork live in @sonordev/press-kit, a companion built on Site Kit. Legacy article imports remain compatible in 8.x.
Resonance measurement
Site Kit 8.13 shows Sonor's privacy choices by default. SiteKitLayout mounts a
childless measurement runtime and, on a site with an enabled measurement
configuration and no consent manager of its own, shows a small notice and a
Privacy choices button, so the site needs no consent code. A site with its own
consent manager passes privacyChoices={false} and connects that manager
through @sonordev/site-kit/resonance before
enabling measurement. Advertising eligibility uses current server receipts, and
the existing analytics provider stays the pageview counter. Analytics wait for a
visitor's choice only when the site's measurement policy requires it, and a
visitor's refusal of visit measurement stands. A site on
@sonordev/agency-site-kit's AgencySiteKitLayout gets the same runtime and
choices from it. Meta browser delivery remains blocked pending verified
automatic collection controls.
Install
npm install @sonordev/site-kitSelling products, events or memberships? Add the companion package too: npm install @sonordev/commerce-kit. See Commerce and memberships.
Publishing articles? Add npm install @sonordev/press-kit alongside Site Kit 8.3 or newer. See Moving to Press Kit.
What's new in 8.0
- Commerce and memberships are their own package. Products, services, events, checkout and the new memberships module now live in
@sonordev/commerce-kit, which builds on site-kit and releases on its own. A site that doesn't sell anything changes nothing. A site that does swaps the package name in its imports:npx sonor-setup codemod --only site-kit-8 --write, then install and build. See docs/MIGRATING-TO-8.md. - The retired Engage and CMS entries are removed, as the 7.x notes said:
@sonordev/site-kit/engage,/cmsand/website/cms, andManagedContentwith its data helpers. A site that never imported them changes nothing. The deprecated aliases for renamed modules (./middleware,./og,./llmsand the rest) still work. - A documented entry for kits.
@sonordev/site-kit/runtimeis the browser transport and API-address reader that packages like commerce-kit build on.
What's new in 7.0
- Agents can use the site.
npx sonor-setup mcpserves the built-in Sonor tools over MCP (business profile, services, FAQ, pages, articles, reviews, and inquiries when you turn them on), and Sonor's AI Visibility tab shows which agents called them. See src/mcp/README.md. - Organised the way Sonor's dashboard is: one entry per module
(
./website/*,./seo/*,./chat), a types-only root entry, and the setup CLI in its own package,sonor-setup. - ESM only, Next 16 only, 0.6 MB (from 4 MB), with no react-markdown in your install and support for Cache Components.
Move a site when you next touch it: npx sonor-setup codemod --write, then
build. See docs/MIGRATING-TO-7.md.
Setup
One environment variable:
# .env.local
SONOR_API_KEY=sonor_xxxxxxxx_xxxxxCopy the key from app.sonor.io: Projects → your project → Settings → API Keys. Keys start with sonor_. Keep it server-side, with no NEXT_PUBLIC_ prefix.
One layout component:
// 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>
)
}SiteKitLayout is an RSC-compatible async Server Component that auto-composes: analytics tracking, website chat, popups, favicons, and managed scripts. No client-side provider wrapping needed: client modules mount as deferred siblings after {children}, so the page stays server-rendered. Props and module options: src/layout/README.md.
Proxy (optional but recommended):
// proxy.ts
import { createProxy } from '@sonordev/site-kit/proxy'
export default createProxy()
// Inlined on purpose: Next statically parses `config.matcher` at build time
// and rejects an imported value. `siteKitMatcher` is a reference value to
// copy from, never a binding to export.
export const config = {
matcher: [
'/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:ico|png|jpg|jpeg|gif|webp|svg|woff2?)$).*)',
],
}Handles Sonor-managed redirects and security headers. For AI discovery, pass
llmsDiscovery={{ siteUrl }} to SiteKitLayout; its HTML links preserve Next
resource preload headers.
CLI (optional, scaffolds everything):
npx sonor-setup init
npx sonor-setup scaffold # sitemap, robots, llms.txt, middleware, manifest
npx sonor-setup status # health checkModules
Every module has its own README in src/<module>/README.md with full API docs, types, and examples.
Core (every site)
| Module | Import | Purpose | Docs |
|---|---|---|---|
| Layout | @sonordev/site-kit/layout | RSC layout that composes all features | README |
| SEO | @sonordev/site-kit/seo | Managed metadata, schemas, FAQs, internal links | README |
| Analytics | @sonordev/site-kit/analytics | Page views, events, conversions, Web Vitals | README |
| Sitemap | @sonordev/site-kit/seo/sitemap | Auto-generated sitemap with Sonor sync. URLs follow next.config trailingSlash | README |
| Proxy | @sonordev/site-kit/proxy | Redirects, security headers, AI discovery (./middleware is a deprecated alias) | README |
| Redirects | @sonordev/site-kit/seo/redirects | Sonor-managed 301/302 redirect rules | README |
Content
| Module | Import | Purpose | Docs |
|---|---|---|---|
| Articles | @sonordev/press-kit/articles | Sonor-managed articles with SSG, topic clusters, E-E-A-T | README |
| Images | @sonordev/site-kit/website/images | Managed image slots with dev-mode editing | README |
| Reputation | @sonordev/site-kit/reputation | Reviews, testimonials, rating stats | README |
Engagement
| Module | Import | Purpose | Docs |
|---|---|---|---|
| Website chat | @sonordev/site-kit/chat | The chat launcher and Echo (Sonor → Messages) | README |
| Popups & Banners | @sonordev/site-kit/website/popups | Popups, banners and toasts from Sonor → Website, drawn in the site's own design | README |
| Forms | @sonordev/site-kit/forms | Managed forms with CRM routing, multi-step, validation | README |
| Sync | @sonordev/site-kit/sync | Booking/scheduling widget (Calendly-like) | README |
| Signal | @sonordev/site-kit/signal | A/B experiments, behavior tracking, real-time config | README |
Commerce and memberships
Products, services, events, checkout and memberships live in @sonordev/commerce-kit, which builds on site-kit and releases on its own. Install it beside site-kit: npm install @sonordev/commerce-kit. Each module also has a /server entry for server components and route handlers.
| Module | Import | Purpose | Docs |
|---|---|---|---|
| Commerce | @sonordev/commerce-kit/commerce | Products, services, events, checkout | Docs |
| Memberships | @sonordev/commerce-kit/memberships | Sell a membership and let members in | Docs |
Upgrading a site that imports commerce from site-kit? That entry moved in 8.0: see Moving a site to site-kit 8.
GEO / AEO (AI Visibility)
| Module | Import | Purpose | Docs |
|---|---|---|---|
| LLMs | @sonordev/site-kit/seo/llms | llms.txt, AEO components, Speakable schema | README |
| LLMs Contract | @sonordev/site-kit/seo/llms/contract | Shared types/sanitizers (the APIs use @sonordev/contracts/llms, the same code) | README |
| MCP | @sonordev/site-kit/mcp | MCP endpoint, server card, in-page WebMCP tools | README |
| Sonor MCP tools | @sonordev/site-kit/mcp/sonor | The built-in tools (sonorMcpServer) and tool-call reporting to Sonor | README |
Motion
Three tiers as three subpaths: a site only installs and ships what it imports. Server HTML always stays visible; above-the-fold content is never animated in.
| Module | Import | Purpose | Docs |
|---|---|---|---|
| Motion | @sonordev/site-kit/motion | <Reveal>, <Parallax>, <ScrollScene> and the scroll engine; zero deps, ~2KB | README |
| Motion / GSAP | @sonordev/site-kit/motion/gsap | Lazy-loaded GSAP timelines (useGsap); optional peer gsap | README |
| Motion / three | @sonordev/site-kit/motion/three | WebGL stages on the engine (useThreeStage); optional peer three | README |
Liquid Glass chrome
| Module | Import | Purpose | Docs |
|---|---|---|---|
| CTA bar | @sonordev/site-kit/website/cta-bar | <CtaBar> + <CtaBarAction>: the floating glass mobile CTA bar. Hides over its form and while typing, compacts on scroll, lifts the Echo launcher, emits cta_click. Server component. | README |
Echo's launcher and chat window use the same glass recipe; see Website chat.
For kits built on site-kit
| Module | Import | Purpose | Docs |
|---|---|---|---|
| Runtime | @sonordev/site-kit/runtime | The browser transport (sonorFetch) and API-address reader that packages like commerce-kit build on. A site doesn't need it | README |
How It Works
SONOR_API_KEY in .env.local
│
▼
SiteKitLayout (RSC server component)
├── Server-side:
│ ├── ManagedFavicon (Sonor logo → <link> tags)
│ ├── ManagedScripts (tracking pixels, analytics tags)
│ └── API preconnect hints
│
├── Client-side (childless siblings after {children}, deferred to idle):
│ ├── AnalyticsProvider (page views, scroll depth, Web Vitals)
│ ├── SitePopups (popups, banners, toasts)
│ ├── SiteChat (website chat: Echo)
│ ├── SignalBridge (A/B experiments, opt-in, not deferred)
│ ├── SitemapSync (browser sitemap fallback, opt-in)
│ └── FleetHeartbeat (kit version + modules, once per session)
│
└── Middleware (separate):
├── Redirects (Sonor-managed 301/302)
├── Security headers (CSP frame-ancestors, nosniff, etc.)
└── AI discovery (HTML rel="describedby" → /llms.txt)
All data flows through the Sonor API (api.sonor.io) authenticated by your API key. No direct database access, no Supabase keys exposed to the client.
Import Paths
// Core
import { SiteKitLayout } from '@sonordev/site-kit/layout'
import { createProxy, siteKitMatcher } from '@sonordev/site-kit/proxy' // in proxy.ts
// SEO
import { getManagedMetadata, ManagedSchema, ManagedFAQ } from '@sonordev/site-kit/seo'
// Analytics
import { AnalyticsProvider, useAnalytics, WebVitals } from '@sonordev/site-kit/analytics'
// Forms
import { ManagedForm, useForm, formsApi, field } from '@sonordev/site-kit/forms'
// Articles (server components; keeps server-only data helpers out of client bundles)
import { Article, ArticleList, ClusterLandingPage } from '@sonordev/press-kit/articles/server-ui'
import { getArticle, generateArticleStaticParams } from '@sonordev/press-kit/articles/server'
// Commerce and memberships are their own package: npm install @sonordev/commerce-kit
import { OfferingCard, ProductPage, EventCalendar } from '@sonordev/commerce-kit/commerce'
import { getOfferingBySlug } from '@sonordev/commerce-kit/commerce/server'
import { MembershipCheckoutButton } from '@sonordev/commerce-kit/memberships'
import type { CommerceOffering } from '@sonordev/commerce-kit'
// Booking
import { BookingWidget } from '@sonordev/site-kit/sync'
// Website chat, and popups (SiteKitLayout mounts both; its `chat` and `popups` props turn them off)
import { SiteChat, ChatWidget } from '@sonordev/site-kit/chat'
import { SitePopups, PopupBlocks } from '@sonordev/site-kit/website/popups'
// Signal (A/B)
import { SignalBridge, SignalExperiment, useSignal } from '@sonordev/site-kit/signal'
// GEO / AEO
import { createLLMsTxtHandler, buildAiDiscoveryHeaders } from '@sonordev/site-kit/seo/llms'
import { AEOBlock, AEOSummary, AEOSteps, SpeakableSchema } from '@sonordev/site-kit/seo/llms'
// Agent tools (MCP): see src/mcp/README.md, or run `npx sonor-setup mcp`
import { createMcpHandler, createMcpServerCardHandler } from '@sonordev/site-kit/mcp'
import { sonorMcpServer, reportToolCallsToSonor } from '@sonordev/site-kit/mcp/sonor'
import { WebMcpTools } from '@sonordev/site-kit/mcp/client'
// Sitemap
import { createSitemap } from '@sonordev/site-kit/seo/sitemap'
// Images
import { ManagedImage } from '@sonordev/site-kit/website/images'
// Reputation
import { TestimonialSection, fetchReviews } from '@sonordev/site-kit/reputation'
// Redirects
import { handleManagedRedirects } from '@sonordev/site-kit/seo/redirects'
// Robots (the AI crawler helpers live in /llms; /robots re-exports them)
import { createRobots, buildAiCrawlerRules, createRobotsTxtHandler } from '@sonordev/site-kit/seo/robots'
// Motion (tier 0, zero deps); tiers 1/2 need `npm i gsap` / `npm i three`
import { Reveal, Parallax, ScrollScene, registerScene } from '@sonordev/site-kit/motion'
import { useGsap } from '@sonordev/site-kit/motion/gsap'
import { useThreeStage, canRunWebGL } from '@sonordev/site-kit/motion/three'
// Liquid Glass mobile CTA bar (server component; pass Next Link via `as`)
import { CtaBar, CtaBarAction } from '@sonordev/site-kit/website/cta-bar'
// Building a package on site-kit (a kit, like commerce-kit): the browser transport
import { sonorFetch, getClientApiConfig } from '@sonordev/site-kit/runtime'
// Styles (optional)
import '@sonordev/site-kit/brand.css'
import '@sonordev/site-kit/forms/styles.css'Environment Variables
# Required (server-only; SiteKitLayout injects into client automatically):
SONOR_API_KEY=sonor_xxxxxxxx_xxxxx
# Optional:
SONOR_API_URL=https://api.sonor.io # Sonor API (default)
NEXT_PUBLIC_SITE_URL=https://example.com # For CLI status checks + sitemap
REVALIDATION_SECRET=your_secret # On-demand ISR for llms.txt
MCP_TRANSPORT_SECRET=... # Netlify MCP relay (npx sonor-setup mcp writes it)The pre-rebrand variables (UPTRADE_API_KEY, NEXT_PUBLIC_UPTRADE_API_KEY) aren't read, and keys with the old uptrade_ prefix aren't accepted. A site that only sets those runs with no key. Move it to SONOR_API_KEY with npx sonor-setup codemod --only uptrade-to-sonor --write.
CLI
The setup CLI is its own package since 7.0, sonor-setup.
npx fetches it; a site that runs it from package.json scripts adds it as a
dev dependency. (sonor-register-sitemap, the postbuild step, stays here.)
npx sonor-setup <command>
Commands:
init Initialize site-kit in a Next.js project
scaffold Scaffold sitemap, robots, llms.txt, proxy, manifest
mcp Give agents the site's tools (MCP endpoint, server card, relay)
setup AI-powered SEO setup (metadata, schemas, FAQs)
scan Scan codebase for integration opportunities
migrate Migrate detected components to site-kit
sync Sync local content to Sonor
status Health check (API, llms.txt, sitemap, layout)
geo Check GEO/llms.txt wiring
images Scan, upload, and manage images
locations Generate location pages
faqs Sync ManagedFAQ paths
api-routes Generate API proxy routes
install Install @sonordev/site-kit
upgrade Upgrade to latest version
codemod Move an older site to the current site-kit (--check, --write)
next16 Move middleware.ts to proxy.ts
verify Exit 0 when the integration is doneTypeScript
Fully typed. All types are exported from their respective module paths:
import type { LLMsDataResponse, GenerateLLMSTxtOptions } from '@sonordev/site-kit/seo/llms'
import type { ManagedFormConfig, UseFormReturn } from '@sonordev/site-kit/forms'
import type { Article, TopicCluster } from '@sonordev/press-kit/articles'
import type { SiteKitLayoutProps } from '@sonordev/site-kit/layout'
import type { CommerceOffering } from '@sonordev/commerce-kit' // commerce types live in commerce-kitArchitecture Note
@sonordev/site-kit is the client bridge between Next.js marketing sites and the Sonor platform. All persistent data (forms, articles, SEO config, analytics) lives in Sonor; site-kit fetches, renders, and tracks.
- Server components (SEO, Articles, Images): Import directly, RSC-compatible, no provider needed
- Client modules (Analytics, chat, popups, Signal): Lazy-loaded via
SiteKitLayout, tree-shaken - Build-time (Sitemap, llms.txt): Run during
next build, sync to Sonor - Middleware (Redirects, Security, AI Discovery): Runs on every request edge
- Kits (commerce-kit): Packages that build on site-kit's public entries (
runtime,analytics,server) and release on their own
Full docs for every module: sonor.dev.