@uxf/cms

Building blocks for UXF admin / CMS applications: authentication pages and forms, a role-gated page wrapper, an admin layout shell (layout, sidebar, menu, breadcrumbs), a data-grid listing page, a structured content builder, and typed clients for the UXF CMS backend (/api/cms/*). It composes @uxf/ui, @uxf/form, @uxf/data-grid and @uxf/wysiwyg rather than replacing them.

The package has no root entry — everything is consumed through subpath imports (e.g. import { LoginPage } from "@uxf/cms/pages/login-page"). It is Next.js-oriented: pages use getInitialProps and next/router.

When to use

Use @uxf/cms when you build an admin interface backed by a UXF CMS API. It gives you the ready-made auth flow (login, forgotten / renew password, user invite), the admin chrome (layout, navigation menu, breadcrumbs), role-based access control, list screens driven by @uxf/data-grid schemas, and the content builder for editing structured page content.

It is not a general UI kit (@uxf/ui), a form library (@uxf/form), or a data grid (@uxf/data-grid) — it wires those together for the CMS use case. For a plain UI primitive or a standalone form field, reach for those packages directly.

Installation

yarn add @uxf/cms

Peer dependencies: @uxf/core, @uxf/core-react, @uxf/data-grid, @uxf/form, @uxf/router, @uxf/styles, @uxf/ui, @uxf/wysiwyg, @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, @floating-ui/react, axios, axios-hooks, swr, react-hook-form, next (>= 13.2.0), react (>= 18.2.0), react-dom (>= 18.2.0).

Because it builds on @uxf/ui, @uxf/form and @uxf/data-grid, complete their setup as well (see @uxf/ui and @uxf/form) — the UiContextProvider, the token layer, and the component CSS they require.

Setup

1. Providers

Two providers must wrap the app:

• UiContextProvider — configures translations, locale, color scheme and the icon sprite. It internally provides TranslationsProvider (@uxf/core-react/translations), which every @uxf/cms component needs because they use useUxfTranslation. Re-exported as @uxf/cms/ui; see the @uxf/ui setup for its full value.
• CmsProvider — sets up swr (SWRConfig) with a default fetch-based fetcher and an in-memory cache. Accepts an optional swrConfig prop to override the fetcher/provider/config.

import { AppProps } from "next/app";
import { CmsProvider } from "@uxf/cms/context/cms-provider";
import { UiContextProvider } from "@uxf/cms/ui";

export default function App(props: AppProps) {
    return (
        <UiContextProvider value={/* icons, translations, locale, colorScheme — see @uxf/ui setup */}>
            <CmsProvider>
                <props.Component {...props.pageProps} />
            </CmsProvider>
        </UiContextProvider>
    );
}

2. Styles

CSS ships at the same path in the published package as in the source tree (unlike @uxf/ui, there is no flattening). Import the admin-shell bundle once, and the content-builder stylesheet where you render it:

/* admin layout, sidebar, menu, mobile bar, breadcrumbs, login layout, avatar */
@import url("@uxf/cms/utils/styles.css");

/* only where the content builder is used */
@import url("@uxf/cms/content-builder/content-builder.css");

Individual admin stylesheets are also published under @uxf/cms/ui/styles/<name>.css (avatar, breadcrumbs, layout, login-layout, menu, mobile-bar, sidebar) if you prefer to import them selectively. These are on top of the @uxf/ui / @uxf/data-grid / @uxf/form token and component CSS, which you set up per those packages.

3. Tailwind

@uxf/cms ships a Tailwind preset (which itself extends the @uxf/ui preset and adds avatar sizes and data-grid colors). Add it as a preset and include the package's compiled files in content so its class names are not purged:

const cmsTailwindConfig = require("@uxf/cms/utils/tailwind.config");

module.exports = {
    presets: [cmsTailwindConfig],
    content: [
        "./node_modules/@uxf/cms/**/*.js",
        // ...your own app files
    ],
};

4. Translations

@uxf/cms ships its translation dictionaries: the merged default export at @uxf/cms/translations/translations and per-locale JSON at @uxf/cms/translations/{cs,de,en,sk}.json (namespaces such as uxf-cms-login-form, uxf-cms-content-builder, uxf-cms-restricted-page, …). Merge them into the translation function you pass to UiContextProvider, alongside the dictionaries of @uxf/ui, @uxf/form, @uxf/data-grid and @uxf/wysiwyg.

The package also ships translations.d.ts, an ambient augmentation that makes useUxfTranslation type-safe over the combined key set of @uxf/cms + @uxf/data-grid + @uxf/form + @uxf/ui + @uxf/wysiwyg.

5. Icons

@uxf/cms/icons-config re-exports the merged icon set required by the package (the @uxf/ui, @uxf/data-grid and @uxf/wysiwyg sets plus CMS-specific glyphs), in the shape expected by @uxf/icons-generator. Feed it into your icon generation and pass the resulting sprite to UiContextProvider. The shipped icons.d.ts augments the @uxf/ui icon set (@uxf/ui/icon/theme) with these names.

Quick start

Each page is a factory that returns a Next.js page component. A login page:

// pages/admin/login.tsx
import { LoginPage } from "@uxf/cms/pages/login-page";

export default LoginPage({
    title: "Sign in",
    handleError: (error) => {
        // surface the error to the user
    },
    onLoginDone: async (loginResponse, redirectUrl) => {
        // persist loginResponse.access_token / refresh_token, then redirect
    },
    loggedUserRedirectUrl: "/admin",
});

Gate any authenticated screen with restrictedPage, which checks the current user's roles against the backend before rendering:

import { restrictedPage } from "@uxf/cms/security/restricted-page";

function DashboardPage() {
    return <div>Dashboard</div>;
}

export default restrictedPage(DashboardPage, { allowedRole: ["ROLE_ROOT"] });

Entry points

Import paths resolve by filesystem to the compiled output (there is no exports map). This is an overview of the main areas, not an exhaustive list of every submodule.

| Import path | Provides | | --- | --- | | @uxf/cms/context/cms-provider | CmsProvider — the swr provider. | | @uxf/cms/ui | Re-exports UiContextProvider, useComponentContext from @uxf/ui/context. | | @uxf/cms/api | Typed request functions against /api/cms/* (login, getLoggedUser, contentGet / contentCreate / contentUpdate, getFormSchema / getFormValues / saveFormValues, dataGridSchemaGet, autocomplete, userConfigGet / userConfigSave, …) and their request/response types. | | @uxf/cms/api/swr | SWR hooks (useCmsMeQuery, useCmsUserConfigQuery, useCmsUserConfigUpdateMutation) and the ApiError class. | | @uxf/cms/security/restricted-page | restrictedPage — role-gated page wrapper. | | @uxf/cms/security/use-logged-user | useLoggedUser — current-user SWR hook. | | @uxf/cms/pages/login-page | LoginPage factory. | | @uxf/cms/pages/forgotten-password-page | ForgottenPasswordPage factory. | | @uxf/cms/pages/renew-password-page | RenewPasswordPage factory. | | @uxf/cms/pages/invite-user-page | InviteUserPage factory. | | @uxf/cms/pages/content-builder | ContentBuilderPage, ContentField and content mapping helpers. | | @uxf/cms/pages/grid-page | GridPage factory (deprecated — prefer a project-specific DataGrid). | | @uxf/cms/forms/login-form | LoginForm. | | @uxf/cms/forms/forgotten-password-form | ForgottenPasswordForm. | | @uxf/cms/forms/renew-password-form | RenewPasswordForm. | | @uxf/cms/forms/invite-user-form | InviteUserForm. | | @uxf/cms/forms/change-password-form | ChangePasswordForm. | | @uxf/cms/forms/components/wysiwyg-input | WysiwygInput — @uxf/form-bound WYSIWYG field. | | @uxf/cms/content-builder | ContentBuilder, ContentBuilderRoot, mapContentResponseToFormData, mapFormDataToContentRequest. | | @uxf/cms/lib/layout | Layout, Breadcrumbs — the admin shell. | | @uxf/cms/lib/login-layout | LoginLayout. | | @uxf/cms/lib/menu | Menu and the menu-item factory (createSection, createLink, createTableLink, createExternalLink, createUserMenu, createSuperSection, createCustomContent). | | @uxf/cms/lib/api | createAxiosInstance — the axios client factory used by @uxf/cms/api. | | @uxf/cms/config | container — a small DI registry the app populates (route resolver, active-route hook, logged-user hooks, notification service) for @uxf/cms internals to consume. | | @uxf/cms/ui/avatar · @uxf/cms/ui/widget · @uxf/cms/ui/copy-to-clipboard · @uxf/cms/ui/copy-to-clipboard-button | Avatar, Widget, CopyToClipboard, CopyToClipboardButton. | | @uxf/cms/utils/tailwind.config | The Tailwind preset. | | @uxf/cms/errors/* | BadRequestError, ForbiddenError, NetworkError, UnauthorizedError, ValidationError (one class per file). |

Gotchas

• No root import. import … from "@uxf/cms" does not resolve; always use a subpath (main points at an index.js that the build does not emit).
• Client components only. Pages, forms and the layout use next/router, useId, SWR and DOM APIs; they are not React Server Component-safe.
• Next.js Pages Router. The page factories return components with getInitialProps and use next/router — they target the Pages Router, not the App Router.
• Both providers are required. UiContextProvider (translations + icons) must be an ancestor of every @uxf/cms component, and CmsProvider must wrap anything using the SWR hooks (useCmsMeQuery, useLoggedUser, GridPage, restrictedPage).
• API base URLs come from env. @uxf/cms/api reads NEXT_PUBLIC_FRONTEND_URL and @uxf/cms/api/swr reads API_URL; requests hit /api/cms/* on that origin.
• The deprecated/ directory (withAuthenticate, the security authorizator) and GridPage are kept for backward compatibility — do not use them in new code.

Links

• @uxf/ui — UI primitives and the UiContextProvider / CSS setup this package builds on.
• @uxf/form — the react-hook-form fields the CMS forms are built from.
• @uxf/data-grid — the grid behind the list screens.