@sonordev/site-kit

v2.6.0

Published

16 days ago

Complete client-side integration kit for Sonor - SEO, Analytics, Engage, Forms, Blog

Downloads

626

0High
0Medium
0Low

uptrademedia

ramseydeal

sonor sonordev site-kit seo analytics forms engage blog nextjs react

@sonordev/site-kit

All-in-one integration kit for Sonor-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.

Install

npm install @sonordev/site-kit

Setup

One environment variable:

# .env.local
SONOR_API_KEY=sonor_xxxxxxxx_xxxxx

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

Middleware (optional but recommended):

// 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):

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 | | 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/sitemap | Auto-generated sitemap with Portal sync | README | | Middleware | @sonordev/site-kit/middleware | Redirects, security headers, AI discovery | README | | Redirects | @sonordev/site-kit/redirects | Portal-managed 301/302 redirect rules | README |

Content

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

Engagement

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

Commerce

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

GEO / AEO (AI Visibility)

| Module | Import | Purpose | Docs | |--------|--------|---------|------| | LLMs | @sonordev/site-kit/llms | llms.txt, AEO components, Speakable schema | README | | LLMs Contract | @sonordev/site-kit/llms/contract | Shared types/sanitizers for API consumers | README |

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

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

# 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

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:

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sonordev/site-kit

Install

Setup

Modules

Core (every site)

Content

Engagement

Commerce

GEO / AEO (AI Visibility)

How It Works

Import Paths

Environment Variables

CLI

TypeScript

Architecture Note