# The host-app contract

URL: https://kywi-docs-production.up.railway.app/developing/the-host-app-contract
Type: docPage

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 } = kywi

## lib/kywi.ts

createKywiNextRuntime(config: KywiConfig): KywiNextRuntime

The one config seam. It owns the DB pool, the API handler, the scope and the per-request active site, memoized for the life of the runtime. Its first successful init also starts the scheduler sweep and the webhook retry worker, each on a 60-second interval by default.

## Call the factory once

The runtime memoizes per closure, not per process. One call — the emitted `lib/kywi.ts` — is the supported shape and gives process-level memoization. A second call anywhere gives you a second connection pool, which the module-scope singletons this replaced could not physically do. Import `kywi` from `lib/kywi.ts`; never construct a runtime in a route.

## The 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'

## app/(site)/layout.tsx

What those two stylesheets are for, and the order they cascade in, is [The stylesheet layers of a Kywi project](/developing/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'

## app/(site)/[[...slug]]/page.tsx

## 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'

## middleware.ts

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`](/developing/importing-from-kywi-softwarecore/) covers which entry answers which question.

## If you hand-write the layout, the page route or the scheduler

## Three things the constructors now do for you

Per-group navigation, the URL Override redirects and canonical tag, and the expiration notices are wired by the constructors and the runtime. A hand-rolled replacement has to do each one for itself.

**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 } : {}), })

## app/(site)/layout.tsx — a hand-written layout

**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](/operating/deploying-a-host-app/#nothing-sweeps-unless-you-make-it-sweep) 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](/authoring/publishing-scheduling-and-expiry/) for what the recipient receives.

## A hand-mounted front-of-site editor should pass siteSlug

`createPublicPage` tells the front-of-site editor which site it is on, so a reference copied with Copy reference names the site by slug. A route that mounts `KywiFrontEdit` itself should pass `siteSlug` (the site's config id); one that mounts `OverlayShell` directly passes it as `referenceSite`. Without it the editor falls back to the `kywi:site-id` meta tag that `createSiteLayout` emits on a multi-site config, and otherwise to `_`. The agent can still resolve either, because the page id is unique across sites. See [Hand a module to your agent](/agent/hand-a-module-to-your-agent/).

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](/developing/rendering-a-page-in-coupled-mode/) and [One config, several sites](/developing/one-config-several-sites/).
