@rakun-kit/manager-react

React manager UI and client utilities for Rakun.

Most apps use this package through framework adapters such as @rakun-kit/next/manager, but the runtime components and clients are also published for custom integrations.

Browser App

Render the manager with a manager client and navigation implementation:

import { ManagerBrowserApp, createHttpManagerClient } from '@rakun-kit/manager-react'
import '@rakun-kit/manager-react/styles.css'

const client = createHttpManagerClient({
  baseUrl: '/api/rakun',
})

export function ManagerPage() {
  return (
    <ManagerBrowserApp client={client} pathname={window.location.pathname} basePath="/backend" />
  )
}

ManagerBrowserApp creates browser path navigation by default. Use ManagerRuntimeApp when you need to provide custom navigation.

Built-in screens are split by manager route and loaded on first visit. Lucide names configured for content-type and module-picker icons remain unrestricted; the manager accepts kebab-case or PascalCase names and loads the selected icon on demand. Hosts can use preloadManagerPath when their router wants to prefetch a built-in route chunk.

Realtime synchronization

ManagerBrowserApp and ManagerRuntimeApp read the realtime transport from the core manager.uiLocales bootstrap response. They automatically use polling or SSE according to the configured Rakun platform. Pass the API base URL when a relative realtime endpoint must be resolved:

<ManagerBrowserApp
  client={client}
  realtimeBaseUrl="/api/rakun"
  pathname={window.location.pathname}
/>

The default sseRealtime() endpoint resolves to <realtimeBaseUrl>/realtime, so core bootstrap configuration does not repeat the API base path.

Event transports subscribe to invalidation topics published by core. Content collaboration, locale variants, versions, comments, and notifications refresh only after a matching event; their periodic POST requests remain only as the polling fallback. The SSE provider multiplexes all active topics over one EventSource, avoiding per-origin browser connection limits when several manager sessions are open. Custom hosts can also pass a RealtimeProvider directly to ManagerProvider or ManagerAppProvider.

Clients

HTTP client:

import { createHttpManagerClient } from '@rakun-kit/manager-react/client/http'

const client = createHttpManagerClient({
  baseUrl: '/api/rakun',
})

const contentTypes = await client.request('manager.contentTypes')

tRPC client adapter:

import { createTrpcManagerClient } from '@rakun-kit/manager-react/client/trpc'

const managerClient = createTrpcManagerClient(trpcProxyClient)

Custom client:

import { createManagerClient } from '@rakun-kit/manager-react/client/request'

const client = createManagerClient(async (name, input, options) => {
  // call your transport here
})

Navigation

Use createPathManagerNavigation for router integrations:

import { createPathManagerNavigation } from '@rakun-kit/manager-react/state/navigation'

const navigation = createPathManagerNavigation({
  basePath: '/backend',
  push: (href) => router.push(href),
  replace: (href) => router.replace(href),
})

Hosts that own the router can pass a linkComponent to ManagerBrowserApp and use preloadManagerPath from the router package to warm built-in route chunks.

Link fields

The f.link() editor shows a title alongside its destination. Users can paste or type a direct URL, choose the home page, or browse configured page-route types and select one of their entries. Internal selections automatically use the item label when the title is empty. Direct links are stored as { href, title }; internal links as { routeId, contentTypeId, title } so core can resolve localized paths. Persisted legacy URL strings are normalized to { href, title: '' } when loaded and remain editable.

Compound arrays such as f.array(f.link()) are reorderable from their drag handles in the Info editor, without losing unsaved values inside each item.

f.menu() provides a navigation-tree editor intended especially for headers. Every item uses the same internal/direct destination picker as f.link() and can contain child items. Drag vertically to reorder and horizontally to nest or outdent; the level buttons provide the same operations for keyboard users. Removing an item also removes its descendant subtree.

Media uploads

Original file names may contain accents, non-Latin scripts, or emoji. The manager transports those names through ASCII-safe upload headers and core restores them before saving media metadata.

The optimization popover separates Image and Video settings through its Format selector. Images retain their normal format and responsive-image controls; videos have their own quality and are converted to both MP4 and WebM.

With optimization enabled in the media toolbar, an image or video's context menu offers Reimport. It regenerates the configured outputs while retaining the existing media record and all relations to it. Multi-select supports the same reimport action from the selection toolbar. Optimization is on by default, and generated image previews are stored as inline data:image/... LQIP values on the media record.

An image's context menu also offers Replace image. The selected file replaces the stored image and generated variants while retaining the existing media ID, name, title, alt text, folder, status, and every relation to it. Rakun also revalidates directly referencing pages when route revalidation is configured. The image editor can crop to a rectangle or circle, rotate, and flip the saved copy horizontally or vertically.

Dynamic data mappings

Fields configured with core .help(text) show a compact help icon beside their label. Activating it opens the guidance in a popover, including for inline modules and nested content types. Translation keys are resolved with the active manager locale, while unregistered strings are displayed directly.

The list mapping editor supports recursive blocks targets. Select Nested list for a mapped list property to configure its own source, query, filters, item type, and field mapping. Current document query values inside that nested editor resolve against the parent source item.

Arrays of links and arrays of relations, including relation().multiple(), can choose Direct field to bind the whole array or Nested list to map every source item. Link items show title and href; relation items show the fields of the related content type. Unlike blocks, these homogeneous arrays do not add a { name, value } wrapper to resolved items.

When an array or .multiple() relation, file, select, or content-reference field declares core .min(count) or .max(count) limits, its editor shows the current count and configured range. It reports values outside that range and prevents confirming or adding beyond the maximum.

A target link appears as separate <field>.title and <field>.href mapping rows, so its label and destination can come from different source fields.

SEO field mappings can use compatible fields from the full current document. New documents also honor core string-field .seo('<seoField>') configuration as an editable initial dynamic data binding.

llms.txt settings

Settings → AI content manages the optional, site-level llms.txt Markdown guide served to AI tools. Editors can enable publishing, override the SEO-derived title and summary, add guidance, and order sections containing internal pages or external URLs. Marking a section as Secondary content places it under ## Optional while preserving its title as a subsection in the generated document. For content types with publication states, the internal page picker only offers published documents. Nothing is added automatically from the sitemap.

Authenticated manager layouts place a Visit site action at the top-right of the logo block. It opens SEO siteUrl in a new tab, falling back to / on the manager host until that setting is configured. A published document with a resolved page route also gets a contextual View page button in its edit toolbar; the URL follows the selected manager language and locale variant.

Routeable content splits its SEO tab into Metadata and Analysis. Generate report renders the current unsaved form through the configured preview and reports metadata lengths, heading structure, missing image alt attributes, indexability, social metadata, rendered JSON-LD blocks, and Google and sharing previews. JSON-LD results identify invalid JSON and missing @context or @type. For saved documents, the report is stored with its score and date when the editor can create SEO reports. Previous reports for the active language and route can be reopened directly from the document's Analysis view. A protective noindex on the temporary preview URL does not affect the content's indexability result.

The secondary sidebar also includes a site-wide SEO screen above the media library. It audits stored metadata for published routeable documents in the active language, treats global default titles and descriptions as valid fallbacks on the home page and warns when another page relies on them, highlights duplicates and incomplete custom Open Graph data, and stores every run so its score can be followed over time. Access and report creation reuse the SeoSettings read and own permissions. Evolution snapshots and recent page reports are fetched and displayed in bounded, paginated groups.

Collaborative content editing

Existing content documents use a Yjs working document keyed by content type and document _id; each draft therefore has its own room. Edits synchronize through the manager HTTP client and remain shared unsaved changes until Save. Save flushes pending CRDT updates, then core materializes and validates the server-side working state before updating MongoDB and revalidating. Public pages continue to use the previous saved snapshot while editors type.

The edit header shows collaborative presence per browser tab. Two tabs for the same account therefore appear independently. After two visible avatars, the group collapses to +N; its tooltip lists all viewers and their focused field, and fields focused in another tab are highlighted in the form. Presence is ephemeral and does not affect the saved working document. With SSE it follows the authenticated stream lifecycle and server heartbeat, without a periodic collaboration sync request. The polling fallback refreshes it during polling.

The manager persists each user's collaborative rooms in IndexedDB. Previously opened content and Template fields load from the local Yjs cache first, remain editable during a temporary connection loss, and synchronize when the server is reachable again. The toolbar distinguishes this locally stored offline state from a snapshot committed by Save.

The shared Template editor has its own Yjs room keyed by content type, so it is collaborative across editors even when they opened different documents. Its snapshot is persisted only by Save and remains separate from every document room.

The edit toolbar offers a confirmed Discard changes action that restores the last saved shared state, including an unsaved shared Template when applicable. Its save menu can also save the current form as a named draft variant copy or create an independent draft copy.

Create-form content becomes collaborative after its first save. Route-layout overrides, Settings, literals, users, comments, reviews, and other administrative forms are intentionally not CRDT-backed. Content translation updates the shared working state and also waits for Save.

Variant lifecycle and locale assignments stay transactional, but their manager queries refresh while editors are open so changes made by another user appear without a page reload.

Styles

Import the package stylesheet once:

import '@rakun-kit/manager-react/styles.css'

Manager languages

English and the locale runtime are built into this package. Extra translations ship from a separate package:

bun add @rakun-kit/manager-locales
# or: npm install @rakun-kit/manager-locales

Import only the locale needed by the server bootstrap:

import { esManagerLocalePack } from '@rakun-kit/manager-locales/es'

rakunBootstrap({
  // ...
  managerLanguages: [esManagerLocalePack],
})

Each language has an independent subpath, so application bundlers only include the locales explicitly imported by the host.

Content-type titles and categories can use project-defined message keys without adding them to the built-in ManagerMessageKey union. Add an English partial pack and extend installed locales through managerLanguages:

import { extendManagerLanguagePack } from '@rakun-kit/core/contracts'
import { esManagerLocalePack } from '@rakun-kit/manager-locales/es'

const managerLanguages = [
  {
    code: 'en',
    name: 'English',
    messages: {
      'field.title': 'Title',
      'layoutModule.header': 'Header',
      'project.contentTypes.article.menu': 'Articles',
    },
  },
  extendManagerLanguagePack(esManagerLocalePack, {
    'field.title': 'Título',
    'layoutModule.header': 'Cabecera',
    'project.contentTypes.article.menu': 'Artículos',
  }),
]

Then set menu.title or menu.category to that arbitrary key. Project keys are resolved at runtime but remain outside the static manager catalog.

Field labels use the dynamic field.<fieldName> namespace. A content-type field named title, for example, automatically resolves field.title in edit forms and list columns without adding it to ManagerMessageKey.

Layout module labels follow layoutModule.<layoutKey>. For example, the header slot automatically resolves layoutModule.header in its tab and configuration panel.

Event Logs

Settings → Logs displays the persistent Rakun event stream through the native manager.logs.list operation. The screen supports filters, cursor pagination, and structured event details. Both the settings card and the operation require the system.eventLog.read permission, which can be assigned from Settings → User Roles.

Manager Plugins

Manager plugins run inside the normal providers and can add dashboard routes, sidebar items, and custom field editors:

import {
  defineRakunManagerPlugin,
  ManagerBrowserApp,
} from '@rakun-kit/manager-react'

const analyticsManagerPlugin = defineRakunManagerPlugin({
  id: '@acme/rakun-analytics',
  routes: [{
    id: 'dashboard',
    path: '/analytics',
    component: AnalyticsScreen,
    permissions: ['plugin.analytics.view'],
  }],
  sidebar: [{
    id: 'analytics',
    title: 'Analytics',
    routeId: 'dashboard',
    position: 'primary',
    group: 'Plugins',
  }],
  fieldEditors: {
    '@acme/rakun-analytics.query': QueryEditor,
  },
})

<ManagerBrowserApp plugins={[analyticsManagerPlugin]} {...props} />

Use ManagerFieldEditorProps, ManagerFieldEditorRef, and useManagerFieldValue from @rakun-kit/manager-react/plugins when implementing field editors. Next.js applications should import plugin objects inside a 'use client' wrapper around RakunManagerClientPage; RakunManagerPage accepts that wrapper through managerComponent.

Extending the RichText editor

Manager plugins can register Lexical nodes and React plugins for every RichText field, including fields rendered inside relations, blocks, and modules:

'use client'

import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
import {
  defineRakunManagerPlugin,
  type ManagerRichTextPluginProps,
} from '@rakun-kit/manager-react/plugins'
import { MentionNode } from './MentionNode'

const MentionsPlugin = ({ id }: ManagerRichTextPluginProps) => {
  const [editor] = useLexicalComposerContext()

  // Register commands and listeners on `editor` here.
  return null
}

export const mentionsManagerPlugin = defineRakunManagerPlugin({
  id: '@acme/rakun-mentions',
  richText: {
    nodes: [MentionNode],
    plugins: [
      {
        id: '@acme/rakun-mentions.plugin',
        component: MentionsPlugin,
        placement: 'editor',
      },
    ],
  },
})

Lexical plugin components receive ManagerRichTextPluginProps (the field id, configuration, current content type, and related field metadata) and render inside LexicalComposer, so they can use the normal Lexical React hooks. Supported placements are toolbar, block-format, editor (the default), actions-start, and actions-end. block-format components render inside the manager's block selector and can use ManagerRichTextBlockFormatItem from @rakun-kit/manager-react/rich-text. Contributions keep declaration order unless an explicit order is provided. Node types and plugin ids must be unique; conflicts report both plugin owners. Node replacements use Lexical's standard LexicalNodeReplacement configuration.

Exports

• @rakun-kit/manager-react: manager app, providers, clients, navigation, router, layout, media, and state helpers.
• @rakun-kit/manager-react/client/http: HTTP manager client.
• @rakun-kit/manager-react/client/request: transport-agnostic manager client.
• @rakun-kit/manager-react/client/trpc: tRPC proxy client adapter.
• @rakun-kit/manager-react/app/runtime-app: ManagerRuntimeApp, ManagerBrowserApp.
• @rakun-kit/manager-react/state/navigation: navigation helpers and provider.
• @rakun-kit/manager-react/link: link component provider.
• @rakun-kit/manager-react/i18n: locale runtime, catalog, and locale types.
• @rakun-kit/manager-react/styles.css: bundled manager styles.

Build

bun run build --workspace @rakun-kit/manager-react