docs
    sonor-setup CLI: Overview
    v7.6.0.md

    sonor-setup

    Set up, verify and migrate a Next.js site on Sonor, for @sonordev/site-kit and its Press Kit and Commerce Kit companions.

    npx sonor-setup init            # SiteKitLayout in app/layout.tsx, SONOR_API_KEY in .env.local
    npx sonor-setup scaffold        # sitemap, robots, llms.txt, live updates, proxy, OG card
    npx sonor-setup verify          # exit 0 means the integration is done
    npx sonor-setup codemod --write # move an older site to the current site-kit
    npx sonor-setup mcp             # give agents the site's tools (MCP endpoint, card, relay)
    npx sonor-setup publication --config publication.json --json # preview a publication launch

    codemod --write takes a 2.x-7.x site to the current site-kit in one pass: root imports to their module, old paths to their 7.x homes, middleware.ts to proxy.ts, sonor-setup into devDependencies where scripts run it, and commerce and articles to their own packages for site-kit 8. Anything it can't rewrite safely it flags with the fix.

    • Articles move to Press Kit (--only press-kit): this selection migrates only article imports and their dependencies. All three article entries (/articles, /articles/server, /articles/server-ui) move to the same subpaths of @sonordev/press-kit. The codemod adds ^1.1.0 and raises the Site Kit floor to ^8.4.0, including a lower minor in the same major. Old article imports stay compatible in Site Kit 8.x; this migration makes the package boundary explicit. Keep SiteKitLayout on Site Kit. Commerce imports and dependencies remain unchanged. Use --only site-kit-8 or the full codemod when you want to migrate both companion packages.
    • Commerce moved to @sonordev/commerce-kit (site-kit-8): site-kit 8 takes commerce out of @sonordev/site-kit. The transform rewrites @sonordev/site-kit/commerce and /commerce/server (and /memberships and /memberships/server, which only a pre-release build had) to the same subpaths of @sonordev/commerce-kit, wherever they're quoted: an import, an export ... from, a dynamic import(), an import type. The types the root used to re-export (CommerceOffering, CommerceCategory, CommerceVariant, CommerceSchedule, OfferingType, Cart, CartItem, EventCheckoutProps, CheckoutLineItem) move to the package's root, and a mixed import is split so the rest stays on site-kit. It runs right after site-kit-7, so a 6.x site that imports OfferingCard from the root ends up on the package in one run. Pick it alone with --only site-kit-8. The whole move is in Moving a site to site-kit 8, and the package's docs are at sonor.dev/commerce-kit.
    • package.json follows the imports: when the site's code uses a moved module, the codemod adds the selected companion package to dependencies and raises @sonordev/site-kit to the required version (^8.0.0 for commerce, ^8.3.0 for articles). An exact pin stays exact (7.4.0 becomes 8.0.0), a tilde stays a tilde, and only those lines change. A site that uses neither moved module stays on the Site Kit it has. A workspace:, link:, file: or git spec isn't rewritten, since the codemod can't read a release from it; it flags the line instead. After a write it prints the install for your package manager, then verify.
    • What it reads: source files anywhere in the project (.ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts and .mdx: pages/, hooks/, scripts/ and a root config count, not just app/ and src/), plus package.json, env files, next.config, pnpm-workspace.yaml and the stylesheets under app/, src/ and components/. It skips node_modules, build output (.next, dist, build, out, coverage) and public/. Run it in the app's folder: it stops at a workspace root, where the code is in the apps, and inside one of our own packages.
    • It goes by imports: a project uses a moved module when its code imports it (import, export ... from, import() including inside next/dynamic, require()). A path in a comment, written out inside a string or template (a code sample, a redirect table, a list of packages), or in a JSX element's text or an MDX page's prose or code fences, isn't an import: the codemod leaves it as it is and adds no package for it. In an MDX page, only the import and export blocks are code.
    • The release-age policy: when pnpm-workspace.yaml lists @sonordev/site-kit under minimumReleaseAgeExclude, the codemod adds the companion packages beside it, quoted the way the list quotes site-kit (a YAML value can't start with @ unquoted), so the first install after a release isn't refused. It also quotes a scoped name it finds there unquoted, which leaves the file unreadable to pnpm. A list with a @sonordev/* wildcard, or one that doesn't list site-kit, is left alone.
    • --check is the gate. It exits 1 while a file needs rewriting and while a manual follow-up remains, so exit 0 means nothing is left for you to do. --dry-run never writes, even beside --write. The next step a preview prints is the same run with --write: it repeats your --only and --path. --only takes the ids --help lists, and an id it doesn't know stops the run (exit 2) instead of running every transform.
    • A file it can't change safely is left as it is: one that isn't UTF-8 is reported with the change it needs, and a write that fails (permissions, a full disk) is reported while the rest are written. It writes package.json and pnpm-workspace.yaml last and exits 1; fix the file and run it again to finish.
    • What it flags instead of guessing: a require() of an old path (the package is ESM only) or a template-literal specifier of one, a namespace import of the site-kit root that uses one of those types, an export * from the root, a re-export of one of the types, an overrides or resolutions entry that keeps site-kit below 8, a package.json it can't read, and a sonorMcpServer whose offerings option has no reader (see mcp below).
    • The proxy lands where Next reads it: src/proxy.ts when the app is src/app, proxy.ts otherwise. Next ignores a proxy anywhere else without a word, so the codemod also moves one an earlier run left at the root, and doctor warns about it.
    • Nothing extra in the project. Originals of the files it writes go to a folder in your OS temp directory, and it prints where (--no-backup skips them). It never creates or edits .env.example: .env.local is the one env file.
    • Old fallbacks collapse: process.env.SONOR_API_KEY || process.env.UPTRADE_API_KEY becomes process.env.SONOR_API_KEY.

    mcp includes article tools by default and imports getAllArticles and getArticle from @sonordev/press-kit/articles/server, passing both as articles: { path, readMany, readOne }. It needs Site Kit 8.3 or newer installed and prints a Press Kit install step if needed. --articles /news selects the publication path. --no-articles omits the tools and Press Kit dependency; that form still works on Site Kit 7.3 (8.0 with offerings). Existing custom servers are preserved. Existing built-in files are preserved unless --force is passed; add the readers manually when migrating one.

    mcp --offerings /shop adds the list_offerings tool. In site-kit 8 the tool reads through getOfferingsResult from @sonordev/commerce-kit/commerce/server, so the server file it writes imports that and passes offerings: { path: '/shop', read: getOfferingsResult }. That needs Site Kit 8.0.0 or newer with --no-articles (8.3 when articles are included): on an older one it writes nothing and tells you to upgrade first. If @sonordev/commerce-kit isn't in your package.json, it tells you to install it.

    scaffold writes the live-updates route, app/api/seo-revalidate/route.ts. On a site with articles it passes the publication's path, createRevalidateRoute({ publicationBasePath: '/insights' }), read from the app directory. When more than one folder looks like the publication, it writes the one-line route and lists them. doctor checks for the same form.

    doctor and verify say whether the site can show privacy choices (privacy.choices): the check warns when privacyChoices={false} leaves no consent manager to ask, when the site connects its own consent manager but leaves SiteKitLayout's built-in choices on beside it, when the installed site-kit is from before SiteKitLayout showed them, when the site loads a Google tag or tag manager by hand or sends a Google Ads conversion itself, and when the notice links to a page the site doesn't have. doctor --online and status also ask Sonor whether its measurement configuration answers for the host the site calls itself (measurement.site). They warn when Sonor refuses that host (a different spelling of the project's address, or one the project doesn't list), when the configuration is turned off and when it needs saving again. A refused host records no analytics. For a configuration that's turned off or needs saving again, what they say about analytics follows the saved policy: where it asks visitors to agree to analytics, the site records none, and where it asks only for advertising purposes, analytics keep recording and the built-in privacy choices let a visitor turn visit measurement off. An enabled configuration is described the same way, and a check that can't read the policy says so instead of guessing.

    Every command takes --json and answers with one envelope (ok, status, exitCode, checks, nextSteps), exit codes included, so coding agents can run it without parsing prose. npx sonor-setup manifest --json prints site-kit's agent manifest: the site's installed copy, or the one this package ships for a site that hasn't installed site-kit yet.

    Versions

    sonor-setup 7 works with site-kit 7 and 8. Version 7.4 adds Press Kit migration and reader wiring. Version 7.3 or newer carries the move to site-kit 8 for sites that use commerce: run it while the site is still on site-kit 7, and it rewrites the imports and brings package.json to site-kit 8. install puts the latest site-kit on a new site, and upgrade takes an existing one to the latest, but it stops short of a newer major version (it says so and installs nothing) until you've run codemod --check and pass --major. sonor-setup reads the site's installed site-kit version itself, and reports both (siteKitVersion, setupVersion) in every --json envelope.

    Where it lives

    This package was part of @sonordev/site-kit until 7.0. Its source is in the site-kit repo under packages/sonor-setup, built from there (it shares site-kit's sitemap discovery, OG template and Next.js file rules, compiled from the same source, so the two can't disagree).

    # from the site-kit repo root
    pnpm build:setup
    pnpm test:setup

    Launch a publication

    publication previews by default. Supply your own identity and brand in a local JSON definition:

    {
      "version": 1,
      "name": "Field Notes",
      "description": "Practical ideas from our team, delivered weekly.",
      "siteUrl": "https://example.com",
      "basePath": "/journal",
      "style": "journal",
      "sections": [{ "slug": "practice", "title": "Practice" }],
      "newsletterFormId": "newsletter",
      "brand": { "primary": "#315F73" }
    }

    Choose newsroom for a visual three-column archive, journal for a spacious two-column essay layout with a serif masthead, or briefing for a compact single-column reading list. All collapse on mobile and inherit the site's design tokens. definePublication and PUBLICATION_STARTERS from @sonordev/press-kit/articles/server are the same contract the CLI validates.

    npx sonor-setup publication --config publication.json --json
    npx sonor-setup publication --config publication.json --write --json

    The command creates the publication index, article, category and author routes, newsletter widget, RSS/Atom feeds, news sitemap, article sitemap and a retryable error page. It doesn't overwrite an existing file, create Sonor records, enroll subscribers or publish content. Configure matching real sections, author profiles and the opt-in form in Sonor before launch. Installation uses Press Kit 1.1 and Site Kit 8.4; keep the existing SiteKitLayout and SONOR_API_KEY.

    Run the returned setup and verification steps. For draft previews on the site's own layout and a sent-issue archive, use the Press Kit preview and issue helpers. A client with its own renderer keeps that renderer; the token exchange checks project, site and exact article revision. Add the generated nested sitemap to the site's sitemap index if it has one. A successful scaffold means files were created; launch readiness still requires a successful build and live route verification.

    AI resource discovery

    sonor-setup geo recognizes SiteKitLayout llmsDiscovery={{ siteUrl }} and AiDiscoveryLinks from @sonordev/site-kit/layout. Prefer these static HTML links: they preserve Next's resource preload headers. Existing proxy, next.config, and host HTTP discovery wiring remains recognized for compatibility.