Upgrading from 4.11 to 4.12

Companions:

• Configuration — the current application-owned configuration files and runtime boundaries.
• Configuration API — the exact AdminConfig, ServerConfig, and i18n contracts.
• Internationalization — the separation between host-interface, Byline-admin, and content locales.

Byline 4.12 removes compatibility APIs and gives the browser/SSR admin configuration an unambiguous name. The migration changes application source, but it does not change stored documents, admin locale values, or database schemas.

Update every published @byline/* dependency to 4.12 together. Byline's packages share runtime singletons and cross-package types, so a mixed 4.11 and 4.12 installation is not supported.

Rename the admin configuration API

Rename these @byline/core imports and calls:

These names describe the admin module graph, not the separate @byline/client SDK. Types such as BylineClientConfig in the SDK retain their existing names.

Keep both admin.config.ts registration points under _byline: the dynamic beforeLoad import protects child loaders, and the lazy-route import protects initial hydration and component rendering.

Rename the admin locale axis

Change Byline's admin-language configuration and APIs:

Author locale tuples with { code, nativeName }, and name their defaults next to the tuples:

export const defaultAdminLocale = 'en'
export const defaultContentLocale = 'en'

export const adminLocales = [
  { code: 'en', nativeName: 'English' },
] as const

export const contentLocales = [
  { code: 'en', nativeName: 'English' },
] as const

The CLI still statically reads contentLocales[*].code from byline/locales.ts and i18nConfig.{locales, defaultLocale} from the host frontend's src/i18n/i18n-config.ts. Preserve those export and property names. The host frontend may continue to call its own chrome language an “interface locale”; that is independent from Byline's admin locale.

byline_admin_users.preferred_locale stores only a locale code. Its values and column name do not change, so this rename requires no database or data migration.

Remove Byline's site URL

Delete serverURL from AdminConfig, ServerConfig, and every initBylineCore() call. The host application's public configuration owns its canonical origin.

The sign-in page's Home link now defaults to /, which preserves the link for an integrated same-origin host without configuring an absolute origin. Pass the host's client-safe value when the public site uses another origin or the link should use the canonical absolute URL:

export const Route = createSignInRoute('/_byline/sign-in', {
  homeUrl: getPublicConfig().serverUrl,
})

Do not reuse that site origin as a future remote SDK base URL. A transport client will need its own baseURL or apiURL contract.

Remove deprecated compatibility usage

• Replace CollectionAdminConfig.picker with itemView.
• Import UnifiedFieldValue instead of the removed UnionRowValue alias.
• Stop reading or assigning the removed ReadContext.beforeReadCache property.
• Configure routes.signIn; do not pass signInPath to createAdminLayoutRoute() or call the removed sign-in override helpers.
• Pass a validated redirectTo to SignInForm; its old callbackUrl prop is removed. The host sign-in route's callbackUrl URL search parameter remains a separate, supported contract.

The unused collection serializer and its Serializable* types are also removed. Byline does not yet expose a transport collection descriptor; future HTTP and MCP descriptors will be explicit allowlisted projections.

Verify the migration

Run the normal application typecheck and production build after updating all packages. In a Byline source checkout, also run the generator check, package tests, docs checker, and bundle-boundary tests. Verify that public routes do not load admin.config.ts, @byline/admin, or the editor graph.