@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

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

Staff-only route groups

PrivateLayout's guard checks the session. For a surface that also requires staff, add requireStaff (resolved from useAuth().isAdminUser, the is_staff || is_superuser fold):

<PrivateLayout sidebar={sidebar} header={header} requireStaff>{children}</PrivateLayout>

A signed-in non-staff user gets ForbiddenState instead of the shell — not a redirect to the auth form: they are already signed in, so signing in again cannot grant the privilege, and since the guard saves the current URL first, a redirect would loop back here. Pass forbiddenFallback to supply your own screen. Details: PrivateLayout README.

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} />

Theme

Themes are selected by the host application's CSS import. BaseApp owns only the light/dark class and does not inject token styles at runtime:

@import "@djangocfg/ui-core/styles/full";
@import "@djangocfg/ui-core/styles/presets/macos";

The package exports ThemeStylePresetId and THEME_STYLE_PRESET_ORDER for metadata and selectors. Preset tokens live exclusively in the static CSS files shipped by @djangocfg/ui-core.

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/devtools. 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.

Analytics and auth funnels

BaseApp mounts the first-party AnalyticsProvider once and bridges events from @djangocfg/api/auth. AuthLayout adds a small layouts.auth.step_viewed breadcrumb at each visible step; the server-confirmed auth_login_success event remains the conversion source of truth.

For a custom product goal, use useAnalytics().event(name, props) from @djangocfg/analytics. See that package's README for the typed event catalog, browser facade, and extension pattern. Do not create a second route listener or send analytics directly from a layout.

Snippets

Small surfaces a host mounts once, exported from @djangocfg/layouts and @djangocfg/layouts/snippets:

Concepts and decisions

How the layouts fit together (scroll model, safe-area tokens, PWA/mobile behaviour, decision log): @docs/.

Stories and tests

@djangocfg/layouts/testing is for Storybook and tests only: MockAuthProvider and buildMockUser give useAuth() a fixed session, MockAuthFormProvider and the step components mount a sign-in step without the full AuthLayout. Do not import it from production code.

Package exports

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

License

MIT — DjangoCFG