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.tsx
import { 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, optional Icon (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-items
  • collapsible, collapsed, renderAction
  • context: personal, organization or all, 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

FileOwnerWhat it does
apps/web/config/navigation.config.tsxyouThe sidebar's groups and items
apps/web/config/settings-navigation.config.tsxyouEvery settings page: group, label, icon, when to show it
apps/web/pages/(app)/layout.tsxyouComposes the shell: <AppSidebar navigation={getNavigation(useShared())}>
apps/web/pages/_layouts/settings.tsxyouComposes the settings shell for pages exporting layout = 'settings'
apps/web/components/dashboard-demo.tsx, dashboard-demo-data.tsyouThe demo on /dashboard (fake numbers): replace <DashboardDemo /> and delete both
apps/web/components/app-sidebar.tsxkitSidebar, account switcher (or logo), account menu in the footer
apps/web/components/settings-sidebar.tsxkitThe settings sidebar: Back to app, then the settings groups
apps/web/components/sidebar-shell.tsxkitWhat both sidebars share (provider, account menu, page area)
apps/web/components/settings-page-body.tsxkitSettingsPageBody: the one column width of every settings page
apps/web/lib/settings-navigation.tskitvisibleSettings, the one rule for which settings pages show; the /settings target
apps/web/components/app-page-header.tsxkitAppPageHeader: sidebar button and breadcrumbs
apps/web/components/account-dropdown.tsxkitName, email, Settings, theme, sign out
apps/web/middleware/07.sidebar.tskitReads the collapsed state for the first render
@kit/ui/sidebar-navigation, @kit/ui/app-breadcrumbskitThe 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

  1. Create the page under pages/(app)/; the folder makes it signed-in only. Its loader still calls requireSession({ c }).
  2. Render AppPageHeader first, then PageBody.
  3. Add an item to navigation.config.tsx and its label to messages/<locale>/app.json. A page under settings/ goes in the settings sidebar instead: see Adding a Settings Page.
// apps/web/pages/(app)/projects/index.tsx
import { 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.tsx
import { 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.ts
import { 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: account or organization. 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 their visible gets that organization, never null.
  • visible: when to show the link, from config and organization. Omitted: always. For role checks, prefer hasPermission(organization, permission) from @kit/organizations over 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.
  • SettingsPageBody gives 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.tsx and 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.

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 site
export 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_state cookie (only false collapses; anything else means expanded) and read by middleware/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 inside BrowserOnly (@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' }],
},
],
});
  • header is the top nav, footer the footer's link columns (each with a heading label; legal pages sit in the Legal column).
  • label is a message key in apps/web/messages/<locale>/marketing.json; the footer description and copyright are marketing.footer.description and marketing.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).
  • path is a site path (/faq, /#features) or an https:// 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 (LocalizedLink with reloadDocument, through MarketingLink for 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 with rel="noopener noreferrer".
  • Below the md breakpoint the header's links and buttons move into a menu sheet (SiteHeader from @kit/ui/marketing). The footer (SiteFooter) ends with the theme toggle (when ENABLE_THEME_TOGGLE is 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 from PublicConfig.
  • A label key that doesn't exist renders as written (e.g. app.routes.membrs): check the spelling against app.json.
  • Adding a settings page to navigation.config.tsx: it belongs in settings-navigation.config.tsx, and the page needs export const layout = 'settings'.
  • Treating visible as a guard: a hidden settings page still opens by URL unless its loader refuses.

Next: Theme and Layout →