How to Customize Navigation

Reshape the built-in sidebar without replacing it. You author one host-owned file, src/_navigation.ts, and it reorders, hides, relabels, and re-parents the built-in items. The sidebar ships a fixed set of items such as Orders, Products, and Customers. _navigation.ts is the single source of truth for their shape. It overrides existing items only, so a new item still comes from a page you add.

When to use this vs. a config export. New pages you add via drop-in routes place their own sidebar item through defineRouteConfig({ label, rank, nested }). _navigation.ts is for the items you didn’t create, the built-in ones. The two layer cleanly: custom routes place themselves, and _navigation.ts reshapes the built-ins.

What you’ll build

A vendor sidebar with Orders pinned to the top, Price Lists hidden, and Campaigns moved under Orders.

Register the typed targets

Nav item ids are typed and generated per panel. Register them once with a single ambient reference in your app’s src. The create-mercur-app scaffold already ships this file.

apps/vendor/src/extension-targets.d.ts

/// <reference types="@mercurjs/vendor/extension-targets" />

With it present, id and nested autocomplete and an unknown id fails tsc.

Create src/_navigation.ts

The file is host-owned and underscore-prefixed. Default-export a defineNavigationConfig with an items array of overrides.

apps/vendor/src/_navigation.ts

import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"

export default defineNavigationConfig({
  items: [
    { id: "orders", rank: 0 },              // pin to the top
    { id: "price-lists", hidden: true },    // hide from the sidebar
    { id: "campaigns", nested: "orders" },  // re-parent under Orders
  ],
})

Know the override fields

Each entry targets one built-in item by its stable id.

Field	Type	Effect
`id`	`NavItemId`	Required. The built-in item to override, top-level or nested.
`rank`	`number`	Order within its parent, lower first.
`hidden`	`boolean`	Remove it from the sidebar.
`label`	`string`	Relabel with an i18n key or literal.
`icon`	`ComponentType`	Replace its icon.
`nested`	`NavParentId \| null`	Re-parent under another top-level item. `null` promotes a nested item to top level.

Both id and nested are checked against the panel’s generated NavItemRegistry and NavParentRegistry.

Reload the panel

Open the vendor portal. Orders sits at the top, Price Lists is gone from the menu, and Campaigns now appears under Orders.

The route for a hidden item stays reachable directly by URL unless you also remove it.

Common recipes

export default defineNavigationConfig({
  items: [
    { id: "payouts", label: "Settlements" },        // relabel
    { id: "categories", nested: null, rank: 1 },    // promote a nested item to top level
    { id: "collections", nested: "orders" },        // move a nested item under a different parent
    { id: "inventory", hidden: true },              // hide a built-in
  ],
})

Verify

The top-level order reflects your rank values, with orders first.
price-lists no longer appears in the sidebar.
campaigns renders as a child under Orders.
Set id: "not-an-item". bun run lint (tsc) fails against NavItemRegistry.
Delete _navigation.ts. The default sidebar returns.

FAQ

Can an installed block reorder the sidebar?

No. Navigation is deliberately host-only. Blocks can ship pages, widgets, and custom fields, but the sidebar order stays a single source of truth in your app’s _navigation.ts.

What ids can I target?

Any built-in item, top-level or nested, by its own id, such as orders, products, categories, collections, campaigns, or customer-groups. Let your editor autocomplete id: against NavItemId. The full set is generated into your panel’s extension-targets.d.ts.

Does this work in the admin panel too?

Yes. Drop src/_navigation.ts in the admin app and reference @mercurjs/admin/extension-targets. Each panel ships its own nav id set.

How do I add a brand-new sidebar item?

That’s a drop-in route with a config export. _navigation.ts only reshapes built-in items, it doesn’t create routes.

How-Tos

Integrations

Deployment

What you’ll build

Register the typed targets

Author the navigation file

Common recipes

Verify

FAQ

Next steps

Add a custom panel page

Add a widget

​What you’ll build

​Register the typed targets

​Author the navigation file

​Common recipes

​Verify

​FAQ

​Next steps

Add a custom panel page

Add a widget

What you’ll build

Register the typed targets

Author the navigation file

Common recipes

Verify

FAQ

Next steps