The host-app contract
A Kywi host app owes core five wiring points and three stylesheet imports; the render path lives in the package and is not the project’s to hold.
Core cannot import your kywi.config.ts — a published package has no path back into the app that installed it — so the app hands the config in, once, and every constructor takes the result. That inversion is the entire contract, and it comes to five files.
The five wiring points
lib/kywi.ts builds the runtime. app/(site)/layout.tsx, app/(site)/[[...slug]]/page.tsx and app/admin/[[...admin]]/page.tsx each construct from it and re-export what Next expects. middleware.ts re-exports core's. Nothing else in the render path belongs to the project.
import { createKywiNextRuntime } from '@kywi-software/core/next'
import config from '../kywi.config'
export const kywi = createKywiNextRuntime(config)
// Named accessors for the API + AX route handlers, which want the handler
// rather than the whole runtime.
export const { getKywi, getKywiHandler, getActiveSite } = kywicreateKywiNextRuntime(config: KywiConfig): KywiNextRuntimeThe stylesheet imports cannot move into the package
Next admits a global stylesheet only from a file inside app/, and a package cannot import your site.css in any case. So the two site stylesheets stay in the layout and the admin stylesheet stays in the admin route — three import lines that look like leftovers and are not. Drop the admin one and every admin surface, login included, renders unstyled.
import { createSiteLayout } from '@kywi-software/core/next'
import '@kywi-software/core/site/styles.css'
import './site.css'
import { kywi } from '../../lib/kywi'
import { layers } from '../../kywi.layers'
const layout = createSiteLayout({ runtime: kywi, layers })
export default layout.default
export const dynamic = 'force-dynamic'What those two stylesheets are for, and the order they cascade in, is The stylesheet layers of a Kywi project.
Two shapes that look right and do not build
Route segment config is parsed statically by Next, before anything runs. export const dynamic = page.dynamic is a member expression, so the build fails with Unsupported node type "MemberExpression" at "dynamic" and then Invalid segment configuration export detected. The constructors return no dynamic field at all, precisely so there is nothing to re-export that way; the thin file writes the literal itself. And export const { default } = createPublicPage(…) — the obvious one-liner — is not legal JavaScript: default is reserved in a binding position. Name the members.
import { createPublicPage } from '@kywi-software/core/next'
import { kywi } from '../../../lib/kywi'
import { layers } from '../../../kywi.layers'
const page = createPublicPage({ runtime: kywi, layers })
export default page.default
export const generateMetadata = page.generateMetadata
// A LITERAL, never `page.dynamic`: Next parses route segment config statically
// and fails the build on a MemberExpression.
export const dynamic = 'force-dynamic'The middleware has its own entry
It is the one thing not re-exported from @kywi-software/core/next. The barrel reaches the database, sharp and the AWS SDK; the middleware compiles for the edge runtime and can carry none of that, so it ships as @kywi-software/core/next/middleware with an import list pinned by a boundary test.
export { middleware, config } from '@kywi-software/core/next/middleware'The same wall explains why nothing under core's next entry is a client component: 'use client' walls every export in a file, and a generateMetadata re-exported from such a module fails next build. Core's client components sit behind @kywi-software/core/next/client and cross into the page as references. Importing from @kywi-software/core covers which entry answers which question.
If you hand-write the layout, the page route or the scheduler
Per-group navigation. A layout that builds the tree itself, instead of through createSiteLayout, must pass the viewer’s groups, or every visitor gets the anonymous tree and Nav Visibility by Group does nothing. Resolve them with viewerNavGroupIds and hand them to scope.nav.getTree, getChildren and scope.menus.createHydrationResolver as viewerGroupIds; the resolver option may be a function, called only when a navigation or siteMap module renders. Named menus are never filtered, so they take no such option. A render that reads the session cookie is dynamic, so a host that sets its own Cache-Control or sits behind a cache-everything CDN rule must keep requests carrying a session cookie out of the shared cache.
import { viewerNavGroupIds } from '@kywi-software/core/next'
const viewerGroupIds = await viewerNavGroupIds(kywi) // undefined for an anonymous visitor
const tree = await scope.nav.getTree(siteId, currentPath, {
locale,
...(viewerGroupIds ? { viewerGroupIds } : {}),
})URL Override redirects and the canonical tag. The 308 from a page’s tree path to its override, the 308 from an old address after a move, and the canonical tag all live in createPublicPage. A hand-written catch-all route resolves the override and serves the page there, but sends none of those.
Expiration notices. createKywiNextRuntime starts the scheduler itself and gives it the handler’s email provider and the site-access policy. A host that runs startScheduler on its own should set scheduler: { enabled: false } in the config, or two sweeps run (Deploying a host app covers the switches). Its call must pass emailProvider (handler.emailProvider) and siteAccessPolicy (config.auth). Without emailProvider no notice is sent and recipients stay pending. Without siteAccessPolicy recipients are still checked, but under the default lenient site-access rule, so strictSiteMembership is ignored. The adminBaseUrl option sets the origin of the “Open in the editor” link; there is no config key for it, so it defaults to https:// plus the page’s site domain. See Publishing, scheduling and expiry for what the recipient receives.
The three constructors also take layers — the generated kywi.layers.ts registry that decides which site's and theme's overrides render. That is a chain of its own; see Rendering a page in coupled mode and One config, several sites.