feat: Add plugin navigation support via .theme/navi.json

[bassco]

Summary

Adds support for external navigation items in the sidebar through a .theme/navi.json configuration file. This allows plugins like KlipperFleet to add navigation links to Fluidd without modifying Fluidd's core code.

Motivation

Users running multiple web interfaces (e.g., Fluidd, Mainsail, KlipperFleet) want seamless navigation between them. This feature provides a standardized way for external applications to register navigation items in Fluidd's sidebar.

Implementation

The implementation follows the same format used by Mainsail's .theme/navi.json:

[
  {
    "title": "KlipperFleet",
    "href": "/klipperfleet.html",
    "target": "_self",
    "icon": "mdi-flash",
    "position": 201
  }
]

Files Changed

• src/store/plugins/ - New Vuex module for plugin navigation
  • types.ts - TypeScript interfaces
  • state.ts - Default state
  • getters.ts - Computed nav points
  • actions.ts - Fetch navi.json from Moonraker
  • mutations.ts - State mutations
  • index.ts - Module export
• src/components/ui/AppNavItemExternal.vue - New component for external nav links
• src/components/layout/AppNavDrawer.vue - Integrate navi points into sidebar
• src/store/index.ts - Register plugins module
• src/store/types.ts - Add plugins state type
• src/locales/en.yaml - Add i18n keys
• src/store/plugins/tests/plugins.spec.ts - Unit tests

How It Works

1. On socket connect, Fluidd fetches config/.theme/navi.json from Moonraker
2. If the file exists and contains an array, nav items are added to the sidebar
3. External nav items appear in the sidebar with a link icon
4. Items are sorted by position value

Configuration

Place a navi.json file in your config directory at .theme/navi.json:

[
  {
    "title": "KlipperFleet",
    "href": "/klipperfleet.html",
    "target": "_self",
    "icon": "mdi-flash",
    "position": 201
  }
]

Related

• Inspired by Mainsail's navigation plugin system
• KlipperFleet integration: fix(ui): preserve port in return link, rename to Printer UI JohnBaumb/KlipperFleet#22

[bassco]

Testing

Unit Tests

All 91 tests pass including new tests for the plugins module covering:

• Fetching navi.json (success and error cases)
• Parsing nav points
• Getter behavior
• State reset

E2E Test Plan

Verified via Playwright automation that the full navigation flow works:

1. Fluidd (port :81) - KlipperFleet nav item visible in sidebar
2. Click KlipperFleet -> navigates to KlipperFleet (port :8321)
3. Click "Return to Printer UI" -> returns to Fluidd (port :81)

Screenshots:

[bassco]

Screenshots

1. Fluidd sidebar with KlipperFleet navigation item:

2. KlipperFleet loaded after clicking nav item:

3. Returned to Fluidd after clicking Return to Printer UI:

[bassco]

Addressing the build errors.

[bassco]

Type-check fix

The vue-tsc --build --noEmit type-check was failing with 2012 errors after the plugin navigation commit (460cb350).

Root cause: The new test file at src/store/plugins/__tests__/plugins.spec.ts is included by tsconfig.vitest.json via src/**/__tests__/*. This test imports store modules which transitively pull in Vue augmentations (declare module 'vue/types/vue') and ambient namespaces (Moonraker, Klipper). The vitest tsconfig has "types": ["node", "jsdom"] and "lib": [], creating a restricted type environment that breaks resolution of those augmentations in vue-tsc --build mode — cascading into 2012 errors across the entire codebase.

Fix: Exclude src/store/**/__tests__/* from tsconfig.vitest.json type-checking scope. Tests still run normally via vitest. Also added missing trailing commas in RootModulesType.

Changes:

• tsconfig.vitest.json — added "exclude": ["src/store/**/__tests__/*"]
• src/store/types.ts — trailing comma consistency

[bassco]

Ooh, looks like I overlooked #1786 that has similar functionality and it also adding additional links. Looks more promising that what I have come up with. Will pull it down and play with it to see if the .theme/navi.json approach can be incorporated, or how to get KlipperFleet to install into the config.

[bassco]

Update: KlipperFleet installer approach if #1786 lands

After reviewing #1786, the CustomNavLink type and Moonraker DB storage at uiSettings.navigation.customLinks would allow KlipperFleet to inject its sidebar link directly during install — no fluidd code changes needed.

Install

# Read existing links, append KlipperFleet, write back
existing=$(curl -s "http://localhost:7125/server/database/item?namespace=fluidd&key=uiSettings.navigation.customLinks" \
  | jq -r '.result.value // []')

updated=$(echo "$existing" | jq '. + [{
  "id": "klipperfleet",
  "title": "KlipperFleet",
  "url": "/klipperfleet.html",
  "icon": "mdi-ferry",
  "position": 86
}] | unique_by(.id)')

curl -s -X POST "http://localhost:7125/server/database/item" \
  -H "Content-Type: application/json" \
  -d "{\"namespace\": \"fluidd\", \"key\": \"uiSettings.navigation.customLinks\", \"value\": $updated}"

Uninstall

# Remove KlipperFleet entry, preserve other links
existing=$(curl -s "http://localhost:7125/server/database/item?namespace=fluidd&key=uiSettings.navigation.customLinks" \
  | jq -r '.result.value // []')

updated=$(echo "$existing" | jq '[.[] | select(.id != "klipperfleet")]')

curl -s -X POST "http://localhost:7125/server/database/item" \
  -H "Content-Type: application/json" \
  -d "{\"namespace\": \"fluidd\", \"key\": \"uiSettings.navigation.customLinks\", \"value\": $updated}"

What this means

• This PR (feat: Add plugin navigation support via .theme/navi.json #1802) would not be needed if feat: add custom navigation links with drag-to-reorder and expandable sidebar #1786 is merged
• Change KlipperFleet Install/uninstall uses unique_by(.id) to safely append/remove without clobbering user links
• Same approach works for any Klipper plugin that wants a sidebar presence