Navigation Configuration
The signed-in app shell (sidebar, header, breadcrumbs, account menu) and how to edit its navigation.
Every page in apps/web/pages/(app)/ renders inside the app shell: a sidebar with your navigation and the account menu, and a header with the sidebar button and breadcrumbs. Settings pages use their own sidebar (see Settings Pages). The navigation is defined in apps/web/config/navigation.config.tsx. This file is yours: edit it freely.
This page is part of the Configuration documentation.
The Config
// apps/web/config/navigation.config.tsximport { Home, Settings } from 'lucide-react';import type { NavigationGroup, NavigationItem,} from '@kit/ui/navigation-schema';import { hasSettingsPages, type NavigationContext,} from '#/lib/settings-navigation.ts';import { authPaths } from './auth-paths';const iconClasses = 'w-4';export function getNavigation(context: NavigationContext) { const application: NavigationItem[] = [ { label: 'app.routes.dashboard', path: context.config.appHomePath, Icon: <Home className={iconClasses} />, }, ]; // last, and only when /settings has a page to land on const settings: NavigationItem = { label: 'app.routes.settings', path: authPaths.settings, Icon: <Settings className={iconClasses} />, }; const showSettings = hasSettingsPages(context); return [ { label: 'app.routes.application', children: showSettings ? [...application, settings] : application, }, ] satisfies NavigationGroup[];}The defaults are Application → Dashboard (APP_HOME_PATH, /dashboard) and one Settings item, last, to /settings. Settings pages aren't listed here: they have their own sidebar (see Settings Pages). The item, and the account menu's Settings, show only while hasSettingsPages(context) is true, the rule /settings uses to pick a page. With the shipped entries that's always: Profile is shown to every signed-in user. These are editable defaults; unit tests do not pin their order, labels or destinations.
Navigation renders in the browser, so it can't read env. It's a function of the shared data instead: config (the public config) and organization (the active organization with the user's roles, or null in the personal context). Call it with getNavigation(useShared()).
Entries
Each group has a label and children. Optionally, translate: false shows the label as written instead of looking it up as a message key, truncated with the full text as its tooltip. The settings sidebar uses it for the organization's name. Each child has:
label,path, optionalIcon(a Lucide icon)highlightMatch: a regex string for when the item counts as active (default: the path and anything below it)children: one level of sub-itemscollapsible,collapsed,renderActioncontext:personal,organizationorall, to show an item only in one account context
Typing the lists as NavigationGroup[] and NavigationItem[] (@kit/ui/navigation-schema) makes a wrong key or type fail pnpm check with the file and line.
Showing Items Conditionally
Push items behind an if, with the public flags or the active organization:
export function getNavigation({ config, organization }: NavigationContext) { const application: NavigationItem[] = [ { label: 'app.routes.dashboard', path: config.appHomePath }, ]; // e.g. a page about the active organization if (organization) { application.push({ label: 'app.routes.projects', path: '/projects' }); } return [{ label: 'app.routes.application', children: application }];}Labels
A label is a message key, <namespace>.<key>. The default items use apps/web/messages/en/app.json:
{ "routes": { "dashboard": "Dashboard", "settings": "Settings" } }To add an item, add its key to that file (and to every other locale's app.json), then use it as the label. Render labels with Trans, which falls back to the label itself, so plain text also works:
import { Trans } from '@kit/ui/trans';<Trans i18nKey={item.label} defaults={item.label} />;The App Shell
| File | Owner | What it does |
|---|---|---|
apps/web/config/navigation.config.tsx | you | The sidebar's groups and items |
apps/web/config/settings-navigation.config.tsx | you | Every settings page: group, label, icon, when to show it |
apps/web/pages/(app)/layout.tsx | you | Composes the shell: <AppSidebar navigation={getNavigation(useShared())}> |
apps/web/pages/_layouts/settings.tsx | you | Composes the settings shell for pages exporting layout = 'settings' |
apps/web/components/dashboard-demo.tsx, dashboard-demo-data.ts | you | The demo on /dashboard (fake numbers): replace <DashboardDemo /> and delete both |
apps/web/components/app-sidebar.tsx | kit | Sidebar, account switcher (or logo), account menu in the footer |
apps/web/components/settings-sidebar.tsx | kit | The settings sidebar: Back to app, then the settings groups |
apps/web/components/sidebar-shell.tsx | kit | What both sidebars share (provider, account menu, page area) |
apps/web/components/settings-page-body.tsx | kit | SettingsPageBody: the one column width of every settings page |
apps/web/lib/settings-navigation.ts | kit | visibleSettings, the one rule for which settings pages show; the /settings target |
apps/web/components/app-page-header.tsx | kit | AppPageHeader: sidebar button and breadcrumbs |
apps/web/components/account-dropdown.tsx | kit | Name, email, Settings, theme, sign out |
apps/web/middleware/07.sidebar.ts | kit | Reads the collapsed state for the first render |
@kit/ui/sidebar-navigation, @kit/ui/app-breadcrumbs | kit | The router-free components behind them |
Kit-owned files change with kit updates: customize through your files above rather than editing them, so updates merge cleanly.
Adding a Page
- Create the page under
pages/(app)/; the folder makes it signed-in only. Its loader still callsrequireSession({ c }). - Render
AppPageHeaderfirst, thenPageBody. - Add an item to
navigation.config.tsxand its label tomessages/<locale>/app.json. A page undersettings/goes in the settings sidebar instead: see Adding a Settings Page.
// apps/web/pages/(app)/projects/index.tsximport { PageBody } from '@kit/ui/page';import { AppPageHeader } from '#/components/app-page-header.tsx';export default function ProjectsPage() { return ( <> <AppPageHeader /> <PageBody>…</PageBody> </> );}// navigation.config.tsx: inside a group's children{ label: 'app.routes.projects', path: '/projects', Icon: <FolderIcon className={iconClasses} /> },Settings Pages
Pages under pages/(app)/settings/ render in a settings-only sidebar instead of the app's: Back to app (to the app home), Your account, then a group titled with the active organization's name. They stay in (app)/, so they're still signed-in only.
/settings itself redirects to the first page the user can see: the account's first (Profile, always shown), else the organization's. It answers 404 when none is visible.
Adding a Settings Page
One page file and one config entry. An owner-only Integrations page (the kit's own /settings/billing is the billing page):
// apps/web/pages/(app)/settings/integrations.tsximport { AppPageHeader } from '#/components/app-page-header.tsx';import { SettingsPageBody } from '#/components/settings-page-body.tsx';// the settings shell (pages/_layouts/settings.tsx)export const layout = 'settings';export default function IntegrationsPage() { return ( <> <AppPageHeader /> <SettingsPageBody className="gap-6">…</SettingsPageBody> </> );}// apps/web/pages/(app)/settings/integrations.server.tsimport { HTTPException } from 'hono/http-exception';import { defineHandler } from 'void';import { DELETE_ORGANIZATION, hasPermission } from '@kit/organizations';import { requireActiveOrganization } from '#/lib/organizations.server.ts';export const loader = defineHandler((c) => { // the access check: the nav entry below only hides the link const organization = requireActiveOrganization({ c }); // a permission, not a role name: custom roles keep working if (!hasPermission(organization, DELETE_ORGANIZATION)) { throw new HTTPException(404); } return {};});// apps/web/config/settings-navigation.config.tsx: add to the list// (import Plug from 'lucide-react'){ group: 'organization', label: 'app.routes.integrations', path: '/settings/integrations', Icon: <Plug className={iconClasses} />, visible: ({ organization }) => hasPermission(organization, DELETE_ORGANIZATION),},Then add routes.integrations to messages/<locale>/app.json. The crumbs read Settings › Integrations, and the main sidebar's Settings item and the account menu need nothing.
group:accountororganization. Account pages are the user's own: shown in every context, and open without an organization in organizations-only mode. Organization pages show only while one is active, and theirvisiblegets that organization, never null.visible: when to show the link, fromconfigandorganization. Omitted: always. For role checks, preferhasPermission(organization, permission)from@kit/organizationsover role names. It is navigation only. It doesn't stop anyone opening the URL: the page's loader must check access itself (requireSession,requireActiveOrganization, a permission) and answer 404, as above.- Order counts within a group; the kit places the groups.
SettingsPageBodygives every settings page the same column, so the content doesn't shift as you move between them.export const layout = 'settings'is what puts the page in the settings shell (a Void named layout:apps/web/node_modules/void/docs/guide/pages-routing/layouts.md). It replaces(app)/layout.tsxand keeps the root layout, so put providers both shells need in the root layout.
After changing the entries, open the affected pages and check the visible links and settings shell. Service and page-action tests cover authorization; unit tests do not pin the example navigation configuration.
Breadcrumbs
AppPageHeader builds the crumbs from the URL. Each part of the path gets a crumb when a navigation item has exactly that path (its label, translated) or when the page gives it a label. Group labels are never crumbs, and a part nobody labels is left out, so text from the URL is never shown.
Name the ids in your URLs with labels, keyed by the path segment:
// apps/web/pages/(app)/projects/[id].tsx → Projects › Acme siteexport default function ProjectPage({ project }: Props) { return ( <> <AppPageHeader labels={{ [project.id]: project.name }} /> <PageBody>…</PageBody> </> );}Page labels are shown as text (not translated, never HTML). The locale prefix (/it/projects) is ignored.
Collapsed Sidebar and Mobile
- The header button collapses the desktop sidebar to icons; item labels become tooltips. The choice is stored in the
sidebar_statecookie (onlyfalsecollapses; anything else means expanded) and read bymiddleware/07.sidebar.ts, so the server renders it as the user left it. - Below 768px the sidebar becomes a sheet opened from the same button; following a link closes it.
- Browser-only UI in your pages (charts, anything reading
window) goes insideBrowserOnly(@kit/ui/browser-only) with a same-size fallback, so the server and the first render match.
Active Items
The sidebar highlights the item whose path matches the current one, ignoring the locale prefix: /projects stays active on /projects/42, but not on /projects-archive. Use highlightMatch (a regex string) for anything else. For your own navigation elsewhere, use the same helper:
import { useRouter } from '@void/react';import { isRouteActive } from '@kit/ui/utils';const { path } = useRouter();const active = isRouteActive(item.path, path, item.highlightMatch);Marketing Navigation
The marketing header and footer links (pages/(marketing)/layout.tsx) come from apps/web/config/marketing-navigation.config.ts, also yours:
export const marketingNavigation = MarketingNavigationSchema.parse({ header: [ { label: 'marketing.nav.features', path: '/#features' }, { label: 'marketing.nav.faq', path: '/faq' }, ], footer: [ { label: 'marketing.footer.product', // column heading links: [{ label: 'marketing.nav.faq', path: '/faq' }], }, { label: 'marketing.footer.legal', links: [{ label: 'marketing.legal.privacy', path: '/privacy-policy' }], }, ],});headeris the top nav,footerthe footer's link columns (each with a headinglabel; legal pages sit in the Legal column).labelis a message key inapps/web/messages/<locale>/marketing.json; the footer description and copyright aremarketing.footer.descriptionandmarketing.footer.copyright({productName},{year}).{year}is the year the page was rendered: a cached page keeps it until the next deploy, and the browser doesn't update it (no hydration mismatch).pathis a site path (/faq,/#features) or anhttps://URL. Anything else (javascript:,data:,http:,//host,/../) fails the parse when the app loads, with an error giving the entry's path (["header", 1, "path"]) and the bad value. A label key with no message renders as the key.- Every link, like the header's Sign in, Get started and Dashboard buttons (Dashboard for signed-in visitors, to
APP_HOME_PATH), reloads the document (LocalizedLinkwithreloadDocument, throughMarketingLinkfor nav links) instead of navigating client-side. Cached marketing pages have no CSP, so the next page, often an app or auth page, needs a full load to get its own. Site paths keep the visitor's locale prefix (/it/faq);https://URLs open in a new tab withrel="noopener noreferrer". - Below the
mdbreakpoint the header's links and buttons move into a menu sheet (SiteHeaderfrom@kit/ui/marketing). The footer (SiteFooter) ends with the theme toggle (whenENABLE_THEME_TOGGLEis on) and the language selector (when more than one locale is configured).
Common Pitfalls
- Linking to pages that don't exist: they render the 404 page.
- Importing server config (
*.config.server.ts) here: only type imports are allowed; values come fromPublicConfig. - A label key that doesn't exist renders as written (e.g.
app.routes.membrs): check the spelling againstapp.json. - Adding a settings page to
navigation.config.tsx: it belongs insettings-navigation.config.tsx, and the page needsexport const layout = 'settings'. - Treating
visibleas a guard: a hidden settings page still opens by URL unless its loader refuses.
Next: Theme and Layout →