App Layout Customization
Customize the signed-in SaaS shell under src/modules/layout, and replace the /app home body.
MuseMVP uses one signed-in shell for /app/*. Edit src/modules/layout: sidebar, header, command search, profile menu, and impersonation banner. Page bodies (the /app home, settings, admin) render inside that shell.
This page is signed-in /app chrome and home body. Public landing header/footer stay config-only; public page bodies are sequential JSX in src/app/(landing-page)/[locale]/.... See Custom Landing Page. To drop a Muse Collection issue onto that surface, see Landing Templates.
Layout Entry Point
Session handling and shell mount live in:
src/app/(saas-page)/app/(account)/layout.tsx
That file checks the session, redirects unauthenticated users, and renders AppLayout from src/modules/layout. Nested settings/admin layouts must not add a second <main>.
Shell Files
src/modules/layout/
├── index.tsx # AppLayout
├── app-layout-shell.tsx # sidebar + header + main chrome
├── lib/
│ ├── use-app-nav.ts # nav groups for sidebar and search
│ └── is-active-app-route.ts
└── components/
├── AppSidebar.tsx
├── AppHeaderSearch.tsx
├── ProfileDropdown.tsx
└── ImpersonationBanner.tsxThe shell uses shadcn sidebar primitives (SidebarProvider, Sidebar, collapsible icon mode), a top bar with command search, theme/locale controls, and the profile dropdown.
Customize the Shell
Change navigation in one place
Add, remove, or reorder destinations in src/modules/layout/lib/use-app-nav.ts. Sidebar and command search both read this list. Keep profile-menu destinations aligned when they point at the same routes.
Adjust chrome
Edit app-layout-shell.tsx for header/main spacing, AppSidebar.tsx for the rail, AppHeaderSearch.tsx for ⌘K search, and ProfileDropdown.tsx for the avatar menu.
Put new labels in mvp.json
User-visible shell copy for a derived product goes in both packages/i18n/src/translations/en/mvp.json and packages/i18n/src/translations/zh/mvp.json. Do not put derivative copy in default.json.
Keep session behavior
Leave layout.tsx redirects and SessionUnavailableState alone unless you are intentionally changing auth flow.
Verify
Open /app, /app/settings/*, and /app/admin/* (admin role) and confirm nav, search, and sign-out still match the product.
Customize the /app Home Body
The workbench inside the shell is a different surface from the chrome.
| Piece | File |
|---|---|
| Route | src/app/(saas-page)/app/(account)/page.tsx |
| Home UI | src/modules/dashboard/components/AppHomeOverview.tsx |
| Home helpers | src/modules/dashboard/lib/ |
| Home copy | mvp.json (app.workbench.*) |
The default home shows a greeting, plan/access/API-key/security snapshot cards, and a get-started checklist. The older mock activity table (MockRecentActivityTable) stays in the repo as a table example; the route comments it out instead of deleting it.
To replace the home:
- Keep session checks in
page.tsx. - Comment out
<MockRecentActivityTable />if you re-enable it, then render your component fromsrc/modules/dashboard/. - Put new home copy only in both
mvp.jsonlocale files.
Settings cards
Settings page headers and panels (SettingsShell, SettingsPanelItem) use rounded-xl to match the shell and shadcn cards. Change those shared components if you restyle every settings page at once.
Related Docs
- Theme Modes and Tokens - Theme and token customization
- Landing Templates - Default landing and Collection issues
- Application Configuration - Full config reference
- User Management - Admin users and impersonation banner
Preserve authenticated / unauthenticated / error states from getSessionState(). Render SessionUnavailableState for service failures instead of treating them as logged out. Synchronize Workers page copies and verify both locales and role navigation.