docs
    Guides: Kits
    .md

    Kits

    site-kit covers what every Sonor site needs. A kit adds what one kind of site needs on top of it: a publication's articles, an agency's case studies, a brokerage's listings, a shop's products and memberships. A kit builds on site-kit's transport and credential, tracks through its analytics and sends leads through its managed forms, so a kit site still runs on one SONOR_API_KEY and shows up in the same Sonor project.

    KitForWhat it adds
    press-kitPublications, journals and newsroomsArticles, author and topic pages, editorial photos, newsletter signup, RSS/Atom feeds and news sitemaps
    agency-site-kitAgencies showing client workCase studies from Sonor's portfolio, the rules for which numbers a case study may claim, JSON-LD, live device frames, instant publish and draft preview
    re-site-kitReal estate sitesMLS listings with search and filters, listing pages, IDX attribution, buildings, trending listings, and MCP tools for a buyer's AI assistant
    commerce-kitSites that sell products, events or membershipsProducts, services and events with checkout and registration, plus memberships with email sign-in and members-only pages

    How a kit fits

    • site-kit comes first. Each kit lists @sonordev/site-kit as a peer dependency and uses the copy your site already installs. Wire site-kit as in Get started, then add the kit.
    • Nothing new to configure. The kit reads the same SONOR_API_KEY, server-side, and Sonor works out the project from it.
    • Server-rendered where it can be. press-kit, agency-site-kit and re-site-kit render content on the server, with small client islands for interactions. commerce-kit's storefront components are client components that load their data in the browser, and its /commerce/server entry is for static paths, 404s and metadata.
    • The content lives in Sonor. Articles, case studies and listings are edited in the dashboard, and the live updates route refreshes the pages that show them. Products, events and membership plans are managed there too.

    press-kit

    For a brand-owned publication: a newsroom or journal with its own name, sections, authors and visual language. Press Kit owns the website components and data helpers. Sonor's app and APIs own editorial planning, Broadcast artwork, newsletter scheduling and distribution.

    pnpm add @sonordev/site-kit@^8.4 @sonordev/press-kit@^1.1

    Press Kit 1.1 needs Site Kit 8.4 or later in the 8.x series, React 19, Next.js 16 and Node 20.19 or later. Keep the existing SiteKitLayout and server-side SONOR_API_KEY; there's no extra provider or key.

    // app/journal/[slug]/page.tsx
    import { Article } from '@sonordev/press-kit/articles/server-ui'
    import {
      generateArticleMetadata,
      generateArticleStaticParams,
    } from '@sonordev/press-kit/articles/server'
    
    type Props = { params: Promise<{ slug: string }> }
    const publication = { basePath: '/journal', siteName: 'Our Journal', siteUrl: 'https://example.com' }
    
    export function generateStaticParams() {
      return generateArticleStaticParams(publication)
    }
    export async function generateMetadata({ params }: Props) {
      return generateArticleMetadata((await params).slug, publication)
    }
    export default async function ArticlePage({ params }: Props) {
      return <Article slug={(await params).slug} basePath={publication.basePath} showRelated showToc />
    }
    ImportPurpose
    @sonordev/press-kitTypes
    @sonordev/press-kit/articlesClient widgets such as newsletter signup and synchronous presentation helpers
    @sonordev/press-kit/articles/serverServer-only reads, routing, metadata, schemas, static paths and feeds
    @sonordev/press-kit/articles/server-uiServer-only publication and article components

    Use one routing definition across article links, category routes, feeds, sitemap entries and MCP tools. Custom typography, colors and stage rules belong to each publication; installing the kit doesn't copy another customer's brand or publish content.

    Existing @sonordev/site-kit/articles, /articles/server and /articles/server-ui imports remain compatible in Site Kit 8.3 and later 8.x releases. For new work, use Press Kit. For an existing site, review a scoped migration before writing:

    npx sonor-setup codemod --only press-kit
    npx sonor-setup codemod --only press-kit --write
    pnpm install
    pnpm build
    npx sonor-setup verify

    This migration changes article imports and dependency requirements. It leaves Commerce Kit imports alone and doesn't publish an article or schedule a broadcast.

    Start a new publication

    Use sonor-setup 7.5 or later to generate a publication from a versioned definition. Choose newsroom for a three-column story desk, journal for a two-column editorial layout with serif headings, or briefing for a focused single-column feed. Each collapses to one column on phones.

    {
      "version": 1,
      "name": "Our Journal",
      "description": "Ideas and lessons from our team.",
      "siteUrl": "https://example.com",
      "basePath": "/journal",
      "style": "journal",
      "sections": [{ "slug": "insights", "title": "Insights" }],
      "newsletterFormId": "journal-newsletter",
      "brand": { "primary": "#39bfb0" }
    }

    Save this as publication.json, use an existing newsletter form in this project, then preview the generated files:

    npx sonor-setup@latest publication --config publication.json --json
    npx sonor-setup@latest publication --config publication.json --write --json
    pnpm build

    The command creates article, author, section, feed and sitemap routes under your chosen base path. It preserves existing files and doesn't contact Sonor, enroll subscribers or publish content. Keep credentials and private customer information out of the definition. Read the launch command and full options.

    Preview, distribute and measure

    The server entry supplies revision-bound draft-preview helpers and an archive reader for immutable sent newsletter issues. A custom preview integration must protect the entry route and preview page from indexing, caching and referrer leakage; follow the complete Press Kit preview recipe. Site Kit 8.4 excludes marked private previews from analytics and Signal reporting.

    Sonor's publication workspace handles editorial ownership, source notes, claim review, issue planning and delivery evidence. Public readers receive approved content; private source notes and recipient data stay in Sonor. Newsletter forms report an accepted request while durable enrollment finishes, and double opt-in remains a separate confirmation step when the list requires it.

    Read the Press Kit reference

    agency-site-kit

    For an agency's own site: the work index, a page per case study, and the proof behind every number on it.

    pnpm add @sonordev/agency-site-kit @sonordev/site-kit
    npx agency-site-kit-setup --site-url https://youragency.com --agency-name "Your Agency"

    The setup command scaffolds a /work index, case-study pages, category routes, and the two routes Sonor calls (live updates and draft preview). The renderer it writes is yours to restyle; the kit supplies the rules every case study follows, so a number is always credited to whoever reported it and never overstated.

    Read the agency-site-kit docs

    re-site-kit

    For a brokerage or team site: searchable listings, a page per listing, and the MLS attribution IDX rules require.

    pnpm add @sonordev/re-site-kit
    // app/listings/page.tsx
    import { searchListings } from '@sonordev/re-site-kit/server'
    import { ListingGrid, ListingFilters, ListingPagination } from '@sonordev/re-site-kit'
    
    export const revalidate = 60
    
    export default async function ListingsPage({ searchParams }) {
      const params = await searchParams
      const { listings, pagination } = await searchListings({ city: params.city, page: Number(params.page ?? 1) })
      return (
        <main>
          <ListingFilters basePath="/listings" values={{ city: params.city }} />
          <ListingGrid listings={listings} hrefFor={(l) => `/listings/${l.slug}`} />
          <ListingPagination pagination={pagination} basePath="/listings" searchParams={params} />
        </main>
      )
    }

    The site never holds an MLS credential: Sonor pulls the feed and the kit reads it through the same key as everything else.

    Read the re-site-kit docs

    commerce-kit

    For a site that sells: products and services, events and classes with registration, and memberships. It needs Site Kit 8 or later, React 19 and Node 20.19 or later. It uses the same SONOR_API_KEY and Site Kit runtime as Press Kit, so a publication and a storefront can share one site.

    pnpm add @sonordev/commerce-kit
    // app/shop/page.tsx
    import { ProductGrid } from '@sonordev/commerce-kit/commerce'
    
    export default function ShopPage() {
      return <ProductGrid />
    }
    // app/shop/[slug]/page.tsx
    import { ProductPage } from '@sonordev/commerce-kit/commerce'
    
    export default async function ProductRoute({ params }: { params: Promise<{ slug: string }> }) {
      const { slug } = await params
      return <ProductPage slug={slug} />
    }

    The grid links each product to /shop/<slug>; pass productBasePath to use another path. Products, prices, stock and events are managed in Sonor.

    Memberships live in the same package. MembershipCheckoutButton sends a visitor to checkout, and createMembers() gives you requireMember() for members-only pages.

    Used commerce from site-kit 7? It moved here in site-kit 8. See Migrating to 8.

    Use /commerce for storefront components, /commerce/server for server reads and route helpers, /memberships for membership UI, and /memberships/server for server-side member access. Keep server entries out of client components. Updating imports doesn't migrate customer records or charge a customer.

    Read the commerce-kit docs