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 launchcodemod --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.0and 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. KeepSiteKitLayouton Site Kit. Commerce imports and dependencies remain unchanged. Use--only site-kit-8or 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/commerceand/commerce/server(and/membershipsand/memberships/server, which only a pre-release build had) to the same subpaths of@sonordev/commerce-kit, wherever they're quoted: an import, anexport ... from, a dynamicimport(), 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 aftersite-kit-7, so a 6.x site that importsOfferingCardfrom 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-kitto the required version (^8.0.0for commerce,^8.3.0for articles). An exact pin stays exact (7.4.0becomes8.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. Aworkspace:,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, thenverify. - What it reads: source files anywhere in the project (
.ts,.tsx,.js,.jsx,.mjs,.cjs,.mts,.ctsand.mdx:pages/,hooks/,scripts/and a root config count, not justapp/andsrc/), pluspackage.json, env files,next.config,pnpm-workspace.yamland the stylesheets underapp/,src/andcomponents/. It skipsnode_modules, build output (.next,dist,build,out,coverage) andpublic/. 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 insidenext/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.yamllists@sonordev/site-kitunderminimumReleaseAgeExclude, 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. --checkis 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-runnever writes, even beside--write. The next step a preview prints is the same run with--write: it repeats your--onlyand--path.--onlytakes the ids--helplists, 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.jsonandpnpm-workspace.yamllast 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, anexport *from the root, a re-export of one of the types, anoverridesorresolutionsentry that keeps site-kit below 8, apackage.jsonit can't read, and asonorMcpServerwhoseofferingsoption has no reader (seemcpbelow). - The proxy lands where Next reads it:
src/proxy.tswhen the app issrc/app,proxy.tsotherwise. Next ignores a proxy anywhere else without a word, so the codemod also moves one an earlier run left at the root, anddoctorwarns 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-backupskips them). It never creates or edits.env.example:.env.localis the one env file. - Old fallbacks collapse:
process.env.SONOR_API_KEY || process.env.UPTRADE_API_KEYbecomesprocess.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:setupLaunch 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 --jsonThe 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.