The admin Dashboard is a widget-based grid. Each widget is a self-contained package living in its own kebab-case folder under src/routes/(app)/dashboard/widgets/<folder>/. Packages are discovered at build time by Vite import.meta.glob — no manual registration, no runtime filesystem scans.

📚 Documentation Map

Guide	Description
Architecture	Folder structure, widget.json manifest, registry, and licensing.
Development	Step-by-step guide to building your own dashboard widget.
Marketplace	Publishing dashboard widgets to marketplace.sveltycms.com.

---

🗂️ Package Layout (1 folder = 1 widget)

Every dashboard widget must ship a co-located .mdx file that describes the widget — the marketplace uses it for the package listing card and detail page:

src/routes/(app)/dashboard/widgets/
  system-health/
    index.svelte    # Entry component (fixed name)
    widget.json     # Marketplace manifest (required)
    readme.mdx      # Marketplace description (REQUIRED, fixed name)
  logs/
    index.svelte
    widget.json
    readme.mdx

• Folder — kebab-case package id (system-health, logs, last5-content).
• Component — keeps its descriptive filename; the filename (minus .svelte) is the registry key saved in user layouts, so renaming the folder never breaks saved dashboards.
• widget.json — machine-readable metadata for the marketplace, the in-app catalog, and telemetry.
• <component>.mdx — human-readable marketplace description: features, licensing, data source, and metadata. Required for every package.

🔍 How Discovery Works

Layer	Mechanism
Client registry	+page.svelte — import.meta.glob("./widgets/*/*.svelte")
Server widget picker	+page.server.ts — eager glob, pre-computed at module load
Manifest registry	manifest-registry.ts — import.meta.glob("./*/widget.json")
Telemetry	Reports installed package ids via the manifest registry
Marketplace catalog	Local packages appear in GET /api/marketplace (offline-first merge)

Drop a new folder into widgets/, restart the dev server, and the widget appears in the picker — the same flow a marketplace install uses.

---

🧪 Testing Policy

• Shell tests (tests/unit/routes/dashboard-page-server.test.ts) assert the registry shape, never a fixed widget list — the catalog is install-specific.
• Widget defaults are unit-tested in tests/unit/dashboard/widget-defaults.test.ts.
• Per-widget tests live in the widget’s own folder (widgets/<folder>/tests/) — optional but encouraged for marketplace submissions.

---

Related

• Development Overview
• Dashboard API & Widgets Reference
• Dashboard System Architecture
• Marketplace System