@djangocfg/layouts

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

pnpm add @djangocfg/layouts

/* before @import "tailwindcss" */
@import "@djangocfg/ui-nextjs/styles";
@import "@djangocfg/layouts/styles";
@import "tailwindcss";

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

Quick start

AppLayout wraps BaseApp (theme, auth, analytics, SWR, toasts) and routes the page to the right shell based on path:

<AppLayout
  layouts={{
    public:  { component: PublicLayout,  enabledPath: ['/', '/legal'] },
    private: { component: PrivateLayout, enabledPath: ['/dashboard'] },
    admin:   { component: AdminLayout,   enabledPath: '/admin' },
    noLayoutPaths: ['/embed'],
  }}
  baseApp={{ project: 'my-app', theme: { defaultTheme: 'system' }, auth: { apiUrl: '…' } }}
  i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}
>
  {children}
</AppLayout>

Use BaseApp directly when you don't need route-based layout switching — see AppLayout README for the matching rules, noLayoutPaths, publicChrome, and i18n.routing plumbing.

Pass i18n when using next-intl or any locale-prefixed routing. Without it, the path matcher can mis-strip 2-letter segments (e.g. /ui/* treated as locale ui).

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 | | AdminLayout | Admin console. | — | | ProfileLayout | Profile page — see below. | |

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();
<AppLayout i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>...</AppLayout>

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(...).

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