@djangocfg/layouts

@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.

BaseApp

Root provider (theme, auth, analytics, SWR, toasts). Use when you don't need route-based layout switching.

<BaseApp
  project="my-app"
  theme={{ defaultTheme: 'system', storageKey: 'my-theme' }}
  auth={{ apiUrl: process.env.NEXT_PUBLIC_API_URL }}
>
  {children}
</BaseApp>

Prop	Role
project	Name for monitor / debug. Enables window.monitor.
theme	defaultTheme, storageKey, and optional style (preset + CSS-var overrides).
auth, analytics, centrifugo, errorTracking, errorBoundary, swr, pwaInstall, monitor, debug	Optional integrations.

theme.style

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

Piece	Meaning
preset	One of THEME_STYLE_PRESET_ORDER. Bundles live in THEME_STYLE_PRESETS.
vars.light / vars.dark	Partial ThemeCssVarMap — HSL triplets (192 90% 35%); radius accepts any CSS length.

Presets: default · django-cfg · ios · soft · dense · high-contrast.

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.

AppLayout

Wraps BaseApp and picks admin → private → public layout by path (matchesPath / enabledPath). noLayoutPaths skips the shell entirely (fullscreen / embeds). publicChrome merges navbar/footer/main spacing defaults.

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

i18n is required for correct path matching when using next-intl or any locale-prefixed routing. Without it the fallback regex can mis-strip 2-letter path segments (e.g. /ui/* treated as locale ui).

Layouts

Component	Use
PublicLayout	Marketing / docs. Slots for navbar + footer. All anchors render through <Link> from @djangocfg/ui-core/components — wrap with LinkProvider higher in the tree to inject a locale-aware Link (e.g. next-intl). All three navbars accept controls + i18n to show theme / locale switchers next to UserMenu (same shape as DefaultFooter.controls). See PublicLayout README for full props, navbar variants (FloatingNavbar / FlushNavbar / MinimalNavbar), DefaultFooter, NavAction, NavControls, and hooks.
PrivateLayout	App shell — sidebar + header.
AuthLayout	Sign-in flows.
AdminLayout	Admin console.
ProfileLayout	Profile page — avatar, editable fields, 2FA, tabs, slots (see below).

ProfileLayout

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

Prop	Type	Role
enable2FA	boolean	Show Security tab with 2FA management.
enableDeleteAccount	boolean	Show Delete account in ⋯ menu.
tabs	ProfileTab[]	Extra tabs appended after built-in ones.
slots.headerBadge	ReactNode	Next to user name (plan, role…).
slots.headerMenuItems	ReactNode	Extra DropdownMenuItems in ⋯ menu.
slots.headerAfter	ReactNode	Below avatar row, above tabs.
slots.footer	ReactNode	Below all tab content.

i18n

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

const { locale, locales, changeLocale } = useLocaleSwitcher();
<AppLayout i18n={{ locale, locales, onLocaleChange: changeLocale }}>{children}</AppLayout>

Monitor & debug

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

Utilities

API	Role
useErrorEmitter, emitRuntimeError	Error tracking hooks.
ErrorLayout (/components/errors)	404 / error pages.
RedirectPage	Auth redirect helper.
PrivacyPage, TermsPage, … (/pages/legal)	Legal templates.

Package exports

Path	Contents
@djangocfg/layouts	Barrel.
@djangocfg/layouts/layouts	Layout components.
@djangocfg/layouts/components	Misc.
@djangocfg/layouts/pages/legal	Legal pages.
@djangocfg/layouts/styles	Base CSS.

Extensions

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

License

MIT — DjangoCFG