The Sidebar
The sidebar is the menu on the left of the admin UI. Every resource you may list gets an entry, by itself, the moment node strut migrate creates its table. Packages (the log viewer, billing) add their own pages to it. You decide the label, icon, group, order and badge of each entry.
The smallest example
Section titled “The smallest example”Create a table:
node strut make:migration create_invoices_tablenode strut migrateWhat you’ll see: an Invoices entry in the sidebar, with a receipt icon (guessed from the name), right after you sign in as a user whose InvoicePolicy allows viewAny. Click it: the invoice list.
Who sees an entry
Section titled “Who sees an entry”An entry is shown only when the user may use it: a resource when the policy’s viewAny allows it, a package page when the user has its permission. Everything else is hidden, because an entry that only leads to “access denied” is worse than no entry. Opening the address directly still answers “Nothing here”, and the API refuses the data regardless.
New policies allow only admins, so a new table’s entry is visible to admins until you open the policy up. See Authorization.
Changing an entry
Section titled “Changing an entry”In the resource’s settings file:
import { auto, defineResourceUi } from '@strutvane/ui'
export default defineResourceUi('invoices', { columns: auto(), form: auto(), filters: auto(), label: { singular: 'Invoice', plural: 'Bills' }, navigation: { icon: 'receipt', group: 'Money', order: 1, badge: 'count' },})navigation option |
Means | Example |
|---|---|---|
icon |
One of the built-in icon names (checked by the compiler) | 'receipt' |
group |
A heading to group entries under | 'Money' |
order |
Order inside its group: lower first | 1 |
badge |
'count' for the live number of rows, or a short text |
'count', 'New' |
hidden |
Keep the screens and routes, hide only the entry | true |
The entry’s text is the plural label (label.plural), “Bills” here.
What you’ll see: Bills under a MONEY heading, first in that group, with a pill showing the number of rows (read out by screen readers as “Bills, 12 rows”).
badge: 'count' costs one request
Section titled “badge: 'count' costs one request”A count badge asks the API for the number of rows, so it’s opt-in. Use it for tables people watch (open tickets, new orders), not for every table.
How entries are ordered
Section titled “How entries are ordered”- Entries without a group come first, at the top.
- Then the groups, A to Z by heading.
- Inside a section:
orderascending (entries withoutordercome last), then the label A to Z.
Alphabetical, not migration order, so adding a table never reshuffles the menu. Example result:
DashboardACCESS UsersCONTENT Posts (order: 1) Categories (order: 2) TagsMONEY Bills 12If you don’t set one, the icon is guessed from the table name:
| The name contains | Icon |
|---|---|
user |
users |
invoice |
receipt |
order |
shopping-cart |
product |
package |
customer, contact |
contact |
setting |
settings |
report |
chart-bar |
post, file, document |
file-text |
project |
folder-kanban |
task |
check-square |
payment |
credit-card |
categor (category, categories) |
folder |
tag |
tag |
| anything else | table |
The first keyword the name contains wins, so invoice_lines gets receipt. A misspelt name is a compile error with a suggestion (icon: 'reciept' → “Did you mean ‘receipt’?”).
Adding your own page
Section titled “Adding your own page”A page that isn’t a table (a report, a settings screen, a package’s tool) is added from a service provider:
import { ServiceProvider, type Application } from '@strutvane/framework'
export class AppServiceProvider extends ServiceProvider { override boot(app: Application): void { app.navigation.add({ label: 'Reports', route: 'reports.index', group: 'Insights', icon: 'chart-bar', order: 10 }) }}It’s merged with the resource entries under the same ordering rules. Packages do the same in their own providers: the log viewer adds Logs at /_strutvane/logs under System, visible only with its permission.
Layout, collapsing and phones
Section titled “Layout, collapsing and phones”- Collapse to icons: the “Collapse menu” button at the bottom shrinks the sidebar to icons, with the names as tooltips. Your choice is remembered in your browser.
- Groups fold: click a group heading to fold it (
aria-expandedtells screen readers). - Phones and narrow windows: the sidebar becomes a drawer behind a menu button.
- Keyboard: Tab reaches every entry; the current page is marked with
aria-current. Ctrl/Cmd+K jumps to any screen without the sidebar.
Hiding an entry, keeping the screens
Section titled “Hiding an entry, keeping the screens”navigation: { hidden: true },The routes and screens still work (for links from elsewhere); only the menu entry disappears. To hide it from some users, change the policy instead: that also protects the data.
Common mistakes
Section titled “Common mistakes”A table doesn’t appear in the sidebar
Section titled “A table doesn’t appear in the sidebar”Why: the policy denies viewAny for you, the table is internal (sessions, tokens…), navigation.hidden is true, or migrate hasn’t run since you created it.
Fix: check in that order; node strut model:show <table> says whether a table is internal.
My entry is at the top instead of in its group
Section titled “My entry is at the top instead of in its group”Why: it has no group, and ungrouped entries come first.
Fix: add group: 'Content'.
Two entries are in the wrong order
Section titled “Two entries are in the wrong order”Why: entries without order come after those with one, then A to Z.
Fix: give both an order.
My page entry links nowhere
Section titled “My page entry links nowhere”Why: route takes a route name ('reports.index'), not a path.
Fix: name the route in your routes file, and check with node strut route:list.
Next steps
Section titled “Next steps”- Customising Screens: every other setting in the same file.
- Service Providers: where page entries are added.
- Authorization:
viewAnyand friends.