knossos

The city of the labyrinth — a live map of your frontend pages.

knossos scans your frontend apps' routes and serves a hierarchical, clickable route map: pages grouped by domain, environment switcher, shared identifier inputs that turn dynamic routes (:id) into working links, and a text filter. The scan runs on every page reload, so the map is always in sync with your file-based routing — no snapshot to regenerate.

Install

pnpm add -D knossos

Usage

knossos              # serve the map on http://localhost:5757
knossos -p 8080      # custom port
knossos build        # write a static knossos.html snapshot
knossos --help

knossos looks for an knossos.config.json next to where you run it (override with --config).

Configuration

{
  "title": "Atlas Agora",
  // Link bases; a switcher shows up when there is more than one.
  "environments": [
    { "name": "Local", "base": "https://agora.local" },
    { "name": "Production", "base": "https://agora-quotes.example.com" }
  ],
  // Shared identifier inputs, shown in the global filter bar.
  "params": [
    { "key": "philosopherId", "label": "ID philosophe", "default": "42" }
  ],
  "apps": [
    {
      "name": "Site",
      "framework": "nuxt",             // scanner to use (only "nuxt" for now)
      "pagesDir": "site/app/pages",       // relative to the config file
      "basePath": "",                     // appended to the environment base
      // Optional per-group settings, keyed by first route segment
      // ("_root" for top-level pages). "params" maps a route param
      // to one of the shared identifiers above.
      "groups": {
        "philosophers": {
          "name": "Philosophes",
          "params": { "id": "philosopherId" }
        }
      },
      // Optional human labels, keyed by route.
      "labels": {
        "/philosophers": "Liste des philosophes"
      }
    }
  ]
}

Everything except apps[].name, environments and the scanner-specific fields (pagesDir for nuxt) is optional: groups default to the first route segment, labels to the last one. Declare several apps to get an app switcher. Pages declaring definePageMeta({ layout: '…' }) get a layout badge.

See example/knossos.config.json for a full real-world config.

Frameworks

Route discovery is scanner-based (src/scanners/), one scanner per framework value:

• nuxt (default) — file-based routing: every .vue under pagesDir is a page.

• module — code-declared routes: the app exports an array of route objects and the config maps its fields; knossos extracts them itself (through npx tsx for TypeScript modules), so the app needs no script and no manifest:

  { "framework": "module", "module": "src/router/index.ts", "export": "allRoutes",
    "fields": { "route": "paths.fr", "label": "name", "groupBy": "file" } }

  fields.route names the path field (:param and [param] both work), fields.label a default label (config labels override), and fields.groupBy a field whose first path segment becomes the group.

• manifest — last-resort escape hatch for anything else: the app emits a JSON manifest ({ "routes": [{ "route": "/quotes/[id]", "group": "quotes" }] }) by whatever means, and knossos reads it via "manifest": "path/to/knossos.routes.json".

The scanner interface — (app, rootDir) => [{ route, groupKey, label?, badges }] — is the extension point for other frameworks.

Why not Nuxt DevTools?

DevTools' Pages tab lists routes of one app in dev. knossos is for the map view: several apps side by side, domain grouping, human labels, per-environment deep links with real identifiers filled in — and it works without booting the app.

License

MIT