npm package: @sonordev/site-kit
Description: Complete client-side integration kit for Sonor - SEO, Analytics, Engage, Forms, Blog
Latest version: 2.5.2

# @sonordev/site-kit

All-in-one integration kit for [Sonor](https://sonor.io)-powered Next.js sites. One package, one env var, every module: SEO, Analytics, Forms, Blog, Commerce, Engage, GEO/AEO, Booking, Reputation, A/B Testing, and more — all managed from the Sonor dashboard at [app.sonor.io](https://app.sonor.io).

## Install

```bash
npm install @sonordev/site-kit
```

## Setup

**One environment variable:**

```bash
# .env.local
SONOR_API_KEY=sonor_xxxxxxxx_xxxxx
```

**One layout component:**

```tsx
// 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, Engage widgets, favicons, managed scripts, and sitemap sync. No client-side provider wrapping needed.

**Middleware (optional but recommended):**

```ts
// middleware.ts
import { createMiddleware, siteKitMatcher } from '@sonordev/site-kit/middleware'

export default createMiddleware()
export const config = siteKitMatcher
```

Handles Portal-managed redirects, security headers, and AI discovery headers.

**CLI (optional — scaffolds everything):**

```bash
npx sonor-setup init
npx sonor-setup scaffold   # sitemap, robots, llms.txt, middleware, manifest
npx sonor-setup status     # health check
```

---

## Modules

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](src/layout/README.md) |
| **SEO** | `@sonordev/site-kit/seo` | Managed metadata, schemas, FAQs, internal links | [README](src/seo/README.md) |
| **Analytics** | `@sonordev/site-kit/analytics` | Page views, events, conversions, Web Vitals | [README](src/analytics/README.md) |
| **Sitemap** | `@sonordev/site-kit/sitemap` | Auto-generated sitemap with Portal sync | [README](src/sitemap/README.md) |
| **Middleware** | `@sonordev/site-kit/middleware` | Redirects, security headers, AI discovery | [README](src/middleware/README.md) |
| **Redirects** | `@sonordev/site-kit/redirects` | Portal-managed 301/302 redirect rules | [README](src/redirects/README.md) |

### Content

| Module | Import | Purpose | Docs |
|--------|--------|---------|------|
| **Blog** | `@sonordev/site-kit/blog` | Portal-managed blog with SSG, topic clusters, E-E-A-T | [README](src/blog/README.md) |
| **Images** | `@sonordev/site-kit/images` | Managed image slots with dev-mode editing | [README](src/images/README.md) |
| **Reputation** | `@sonordev/site-kit/reputation` | Reviews, testimonials, rating stats | [README](src/reputation/README.md) |

### Engagement

| Module | Import | Purpose | Docs |
|--------|--------|---------|------|
| **Engage** | `@sonordev/site-kit/engage` | Popups, nudges, bars, chat widgets | [README](src/engage/README.md) |
| **Forms** | `@sonordev/site-kit/forms` | Managed forms with CRM routing, multi-step, validation | [README](src/forms/README.md) |
| **Signal** | `@sonordev/site-kit/signal` | A/B experiments, behavior tracking, real-time config | [README](src/signal/README.md) |

### Commerce

| Module | Import | Purpose | Docs |
|--------|--------|---------|------|
| **Commerce** | `@sonordev/site-kit/commerce` | Products, services, events, checkout | [README](src/commerce/README.md) |
| **Sync** | `@sonordev/site-kit/sync` | Booking/scheduling widget (Calendly-like) | [README](src/sync/README.md) |

### GEO / AEO (AI Visibility)

| Module | Import | Purpose | Docs |
|--------|--------|---------|------|
| **LLMs** | `@sonordev/site-kit/llms` | llms.txt, AEO components, Speakable schema | [README](src/llms/README.md) |
| **LLMs Contract** | `@sonordev/site-kit/llms/contract` | Shared types/sanitizers for API consumers | [README](src/llms/LLM_GEO_CONTRACT.md) |

---

## How It Works

```
SONOR_API_KEY in .env.local
       │
       ▼
SiteKitLayout (RSC server component)
├── Server-side:
│   ├── ManagedFavicon         (Portal logo → <link> tags)
│   ├── ManagedScripts         (tracking pixels, analytics tags)
│   └── API preconnect hints
│
├── Client-side (lazy-loaded island):
│   ├── AnalyticsProvider      (page views, scroll depth, Web Vitals)
│   ├── EngageWidget           (popups, nudges, chat)
│   ├── SignalBridge           (A/B experiments, behavior tracking)
│   ├── SitemapSync            (keeps Portal seo_pages in sync)
│   └── IdentityProvider       (unified visitor/session IDs)
│
└── Middleware (separate):
    ├── Redirects              (Portal-managed 301/302)
    ├── Security headers       (CSP, X-Frame-Options, etc.)
    └── AI discovery           (Link: rel="describedby" → /llms.txt)
```

All data flows through the Portal API (`api.sonor.io`) authenticated by your API key. No direct database access, no Supabase keys exposed to the client.

---

## Import Paths

```ts
// Core
import { SiteKitLayout } from '@sonordev/site-kit/layout'
import { createMiddleware, siteKitMatcher } from '@sonordev/site-kit/middleware'

// 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'

// Blog
import { BlogPost, BlogList, ClusterLandingPage } from '@sonordev/site-kit/blog'
import { getBlogPost, generateBlogStaticParams } from '@sonordev/site-kit/blog/server'

// Commerce
import { OfferingCard, ProductPage, EventCalendar } from '@sonordev/site-kit/commerce'

// Booking
import { BookingWidget } from '@sonordev/site-kit/sync'

// Engage
import { EngageWidget, ChatWidget } from '@sonordev/site-kit/engage'

// Signal (A/B)
import { SignalBridge, SignalExperiment, useSignal } from '@sonordev/site-kit/signal'

// GEO / AEO
import { createLLMsTxtHandler, buildAiDiscoveryHeaders } from '@sonordev/site-kit/llms'
import { AEOBlock, AEOSummary, AEOSteps, SpeakableSchema } from '@sonordev/site-kit/llms'

// Sitemap
import { createSitemap } from '@sonordev/site-kit/sitemap'

// Images
import { ManagedImage } from '@sonordev/site-kit/images'

// Reputation
import { TestimonialSection, fetchReviews } from '@sonordev/site-kit/reputation'

// Redirects
import { handleManagedRedirects } from '@sonordev/site-kit/redirects'

// Robots
import { createRobots } from '@sonordev/site-kit/robots'

// Styles (optional)
import '@sonordev/site-kit/brand.css'
import '@sonordev/site-kit/forms/styles.css'
```

---

## Environment Variables

```bash
# Required (server-only — SiteKitLayout injects into client automatically):
SONOR_API_KEY=sonor_xxxxxxxx_xxxxx

# Optional:
SONOR_API_URL=https://api.sonor.io              # Portal API (default)
NEXT_PUBLIC_SITE_URL=https://example.com         # For CLI status checks + sitemap
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=6Le...            # reCAPTCHA Enterprise (forms)
REVALIDATION_SECRET=your_secret                  # On-demand ISR for llms.txt
```

Legacy env vars (`UPTRADE_API_KEY`, `NEXT_PUBLIC_UPTRADE_API_KEY`) are still supported for older sites.

---

## CLI

```bash
npx sonor-setup <command>

Commands:
  init           Initialize site-kit in a Next.js project
  scaffold       Scaffold sitemap, robots, llms.txt, middleware, manifest
  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 Portal
  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
```

---

## TypeScript

Fully typed. All types are exported from their respective module paths:

```ts
import type { LLMsDataResponse, GenerateLLMSTxtOptions } from '@sonordev/site-kit/llms'
import type { ManagedFormConfig, UseFormReturn } from '@sonordev/site-kit/forms'
import type { BlogPost, TopicCluster } from '@sonordev/site-kit/blog'
import type { CommerceOffering, SizeChart } from '@sonordev/site-kit/commerce'
import type { SiteKitLayoutProps } from '@sonordev/site-kit/layout'
```

---

## Architecture Note

`@sonordev/site-kit` is the client bridge between Next.js marketing sites and the Sonor platform. All persistent data (forms, blog posts, SEO config, analytics) lives in the Portal API — site-kit fetches, renders, and tracks.

- **Server components** (SEO, Blog, Images): Import directly, RSC-compatible, no provider needed
- **Client modules** (Analytics, Engage, Signal): Lazy-loaded via `SiteKitLayout`, tree-shaken
- **Build-time** (Sitemap, llms.txt): Run during `next build`, sync to Portal
- **Middleware** (Redirects, Security, AI Discovery): Runs on every request edge

For the full platform architecture, see the root `CLAUDE.md`.