@djangocfg/layouts

Layouts, app shell, and providers for Next.js App Router. Part of DjangoCFG.

pnpm add @djangocfg/layouts

/* Golden path — bundles Tailwind + tokens + base + utilities, layer-safe */
@import "@djangocfg/ui-core/styles/full";
@import "@djangocfg/layouts/styles";

Peers: @djangocfg/ui-core, React 19, Next.js 16+, Tailwind CSS 4.

Quick start

Two responsibilities, kept separate:

1. Providers — mount BaseApp ONCE at the app root (theme, auth, i18n, SWR, monitor, toasts). It's framework-agnostic (works in Wails/Vite too).
2. Per-section shell — each Next.js route-group layout.tsx imports the matching shell (PrivateLayout / PublicLayout) and passes its own config. No runtime layout-router, no enabledPath matching.

// app/[locale]/layout.tsx — providers, once
import { BaseApp } from '@djangocfg/layouts';
<BaseApp project="my-app" theme={{ defaultTheme: 'system' }}
         auth={{ apiUrl: '…', routes: { auth: '/auth' } }}
         i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>
  {children}
</BaseApp>

// app/[locale]/(pages)/private/layout.tsx — the private shell
import { PrivateLayout } from '@djangocfg/layouts';
<PrivateLayout sidebar={sidebar} header={header}>{children}</PrivateLayout>

See the BaseApp README for the full provider surface and the Next.js vs Wails wiring, and the demo app (apps/demo/app/_layouts) for a complete reference.

Pass i18n when using next-intl or any locale-prefixed routing, so the link bridge and locale switcher resolve correctly.

Layouts

| Component | Use | Docs | |---|---|---| | PublicLayout | Marketing / docs. Slots for navbar (Floating/Flush/Minimal) + footer + locale + auth controls. | README | | PrivateLayout | Authenticated app shell — sidebar (collapsible icon rail, accordion groups, rail/featured/CTA slots) + popover account footer. | README | | AuthLayout | Sign-in / sign-up flows. Shell-based: centered (default) or split (two-column desktop). | README |

Admin is not a separate layout — use PrivateLayout with an admin sidebar config in your app/.../admin/layout.tsx.

AuthLayout shells

Two visual variants, switchable via the variant prop:

• centered — Apple HIG-style: frameless, centered form, animated glow background.
• split — Two-column card on desktop (form left, customizable sidebar right); single-column on mobile. Background image/gradient with overlay + blur via the background prop.

// Split variant with background image and testimonial sidebar
<AuthLayout
  variant="split"
  background={{ imageUrl: '/bg.jpg', overlay: 'hsl(var(--background) / 0.6)', blur: '8px' }}
  sidebar={<Testimonial />}
>
  {/* optional custom header, shown only on identifier step */}
</AuthLayout>

Architecture: AuthShell orchestrator dispatches to CenteredShell or SplitShell. Add new variants by extending AuthShellVariant and creating a new shell component.

ProfileLayout

<ProfileLayout enable2FA enableDeleteAccount tabs={tabs} slots={slots} />

| Prop | Role | |---|---| | enable2FA | Show Security tab with 2FA management. | | enableDeleteAccount | Show Delete account in ⋯ menu. | | tabs | Extra ProfileTab[] appended after built-ins. | | slots.headerBadge / headerMenuItems / headerAfter / footer | Slot content around the avatar row, menu, and tab body. |

Theme

baseApp.theme.style injects <style id="djangocfg-baseapp-theme-style"> with --* CSS variables. Merge order: imported globals → preset → vars (strongest).

| Piece | Meaning | |---|---| | preset | default · django-cfg · ios · soft · dense · high-contrast. | | vars.light / vars.dark | Partial ThemeCssVarMap — HSL triplets (192 90% 35%); radius accepts any CSS length. |

Playground-only buckets (shadows, typography, spacing) are not injected — export full CSS from the Theme Configurator when you need them.

Exports: ThemeStyleConfig, ThemeCssVarKey, ThemeCssVarMap, ThemeStylePresetId, THEME_STYLE_PRESETS, THEME_STYLE_PRESET_ORDER, buildThemeStyleSheet, ThemeStyleBridge.

i18n

import { useLocaleSwitcher } from '@djangocfg/nextjs/i18n/client';
import { routing } from '@djangocfg/nextjs/i18n/routing';

const { locale, locales, changeLocale } = useLocaleSwitcher();
<BaseApp i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>...</BaseApp>

When routing is set, BaseApp mounts a locale-aware <Link> adapter so every layout-rendered link keeps the active locale prefix. Drop it for default-locale-only apps.

Monitor & debug

baseApp.project enables window.monitor. Debug panel: Cmd+D or ?debug=1.

MonitorBoundary

Error boundary that automatically reports caught errors to @djangocfg/monitor. Use at page/layout level so unexpected render errors land in your backend dashboard.

import { MonitorBoundary } from '@djangocfg/layouts';

export default function Layout({ children }) {
  return (
    <MonitorBoundary variant="fullscreen" name="root-layout">
      {children}
    </MonitorBoundary>
  );
}

// Per-section, non-fatal:
<MonitorBoundary variant="card" name="dashboard-stats" resetKeys={[pathname]}>
  <StatsPanel />
</MonitorBoundary>

// Opt out of reporting (e.g. third-party iframe noise):
<MonitorBoundary reportToMonitor={false} variant="silent">
  <EmbeddedWidget />
</MonitorBoundary>

Wraps Boundary from @djangocfg/ui-core — same variant/fallback/resetKeys API, plus auto FrontendMonitor.capture(...).

One top-level boundary. BaseApp already mounts the app-wide crash boundary (UiProviders' built-in one, fed an i18n fallback) — don't wrap a second one around the whole app. Use MonitorBoundary for per-section isolation (so one panel's crash doesn't take the page), not as a duplicate root boundary. All boundaries share the single ui-core Boundary catch.

For local UI widgets that should not report to backend, use Boundary from @djangocfg/ui-core directly.

Package exports

| Path | Contents | |---|---| | @djangocfg/layouts | Barrel. | | @djangocfg/layouts/layouts | Layout components. | | @djangocfg/layouts/components | Misc + ErrorLayout, RedirectPage. | | @djangocfg/layouts/pages/legal | Legal page templates. | | @djangocfg/layouts/configurator | JSON Schemas for <JsonSchemaForm>-driven configurator UIs (PrivateLayout for now). Pair with @djangocfg/ui-tools. | | @djangocfg/layouts/styles | Base CSS. |

Extensions: @djangocfg/ext-newsletter, ext-knowbase, ext-leads, ext-payments, ext-support, …

License

MIT — DjangoCFG