Dashboard Publishing¶

This document defines the end-to-end pipeline for publishing a dashboard: the build contract that dashboard projects must satisfy, the bundle format uploaded to the registry, the CLI commands that drive the workflow, and the validation rules enforced at each step.

Overview¶

Publishing a dashboard is a three-step process:

Developer's machine                          Huitzo Registry
┌──────────────────────────────────┐         ┌─────────────────────────┐
│ 1. Build                         │         │                         │
│    huitzo dashboard build        │         │                         │
│    → npm run build (lib mode)    │         │                         │
│    → dist/main.js (self-contained)         │                         │
│                                  │         │                         │
│ 2. Validate                      │         │                         │
│    huitzo dashboard validate     │         │                         │
│    → Check manifest + bundle     │         │                         │
│                                  │         │                         │
│ 3. Publish                       │         │                         │
│    huitzo dashboard publish      │         │                         │
│    → Create .tar.gz from dist/   │────────▶│ Extract, store, register│
│    → Upload to registry          │         │ Serve at /d/{slug}      │
└──────────────────────────────────┘         └─────────────────────────┘

Build Contract¶

Dashboards are built as self-contained ES module libraries. Each dashboard bundles all of its dependencies — including React, ReactDOM, and the Huitzo Dashboard SDK — so that it has no version coupling with Hub.

Why Dashboards Bundle Everything¶

Hub is a platform that hosts third-party dashboards. If dashboards shared React with Hub, a Hub upgrade (e.g., React 19 → 20) could break every third-party dashboard that hasn't updated. By bundling everything, dashboards are fully independent:

See Loading Architecture — Why Dashboards Bundle Their Own React for the full rationale.

Vite Library Mode¶

The dashboard's vite.config.ts must use library mode to produce an ESM module with mount/unmount exports:

// vite.config.ts — dashboard project build configuration
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js';

export default defineConfig(({ mode }) => ({
  plugins: [react(), cssInjectedByJsPlugin()],
  define: {
    'process.env.NODE_ENV': JSON.stringify(mode),
    'process.env': '{}',
  },
  build: {
    lib: {
      entry: 'src/main.tsx',
      formats: ['es'],
      fileName: 'main',
    },
    cssCodeSplit: false,
  },
}));

No external configuration is needed — all dependencies (React, SDK, etc.) are bundled into the output.

CSS Handling¶

CSS is injected into the JavaScript module — there is no separate CSS file to load. Vite's cssCodeSplit: false combined with library mode injects styles via <style> tags when the module is imported.

This means: - Hub loads one file per dashboard (the JS module) - Styles are automatically applied on import - CSS Modules are still required to prevent style collisions between dashboards

Entry Point Contract¶

The dashboard entry point (src/main.tsx) must satisfy the Module Contract — export mount and unmount functions:

// src/main.tsx — must export mount and unmount
import { createRoot, type Root } from 'react-dom/client';
import type { HuitzoContext } from '@huitzo/dashboard-sdk';
import { HuitzoProvider } from '@huitzo/dashboard-sdk-react';
import { ErrorBoundary } from './components/ErrorBoundary';
import App from './App';

let root: Root | null = null;

export function mount(container: HTMLElement, context: HuitzoContext): void {
  root = createRoot(container);
  root.render(
    <ErrorBoundary fallback={<CrashScreen onReturn={() => context.navigateToHub()} />}>
      <HuitzoProvider context={context}>
        <App />
      </HuitzoProvider>
    </ErrorBoundary>
  );
}

export function unmount(_container: HTMLElement): void {
  root?.unmount();
  root = null;
}

Hub calls mount(container, context) when the user navigates to the dashboard and unmount(container) when they navigate away. The dashboard creates its own React root inside the provided container.

Bundle Format¶

Build Output¶

After huitzo dashboard build (or npm run build), the dist/ directory contains:

dist/
├── main.js              # Self-contained ESM module (React + SDK + app code + CSS)
└── assets/              # (optional) static assets (images, fonts)
    ├── logo-abc123.png
    └── chart-data.json

Upload Artifact¶

The CLI packages dist/ into a gzipped tarball for upload:

claims-dashboard-1.2.0.tar.gz
└── main.js
└── assets/
    └── ...

Size & Content Limits¶

CLI Workflow¶

The dashboard CLI commands (huitzo dashboard validate, build, publish) are documented in the CLI Reference — Dashboard Commands.

Validation Rules¶

Manifest Validation¶

Bundle Validation¶

Pack Dependency Validation (Online)¶

When connected to the registry, the CLI also checks:

Version Management¶

Semantic Versioning¶

Dashboard versions follow semver:

MAJOR.MINOR.PATCH
  │      │      │
  │      │      └── Bug fixes, visual tweaks
  │      └───────── New features, added pages
  └──────────────── Breaking changes to pack dependencies or data format

Active Version¶

Each dashboard has exactly one active version at a time. When a new version is published:

1. The new version record is created with is_active = true
2. All previous versions are set to is_active = false
3. Hub immediately serves the new active version to all users

There is no gradual rollout — the switch is immediate.

Rollback¶

To roll back, publish the previous code with a new patch version:

# If 1.3.0 is broken, check out the 1.2.0 code and publish as 1.3.1
git checkout v1.2.0
# bump version to 1.3.1 in huitzo-dashboard.yaml
huitzo dashboard publish

Deleting a Dashboard¶

To permanently remove a dashboard and all its versions:

huitzo dashboard delete {slug}

This performs:

1. Cascade-deletes the dashboard record, all versions, and access grants from the registry
2. Removes bundle files from disk
3. The dashboard is immediately inaccessible — any cached references in Hub will return 404

This action is irreversible. To temporarily hide a dashboard without deleting it, change its visibility to private:

# pseudocode — hide instead of delete
huitzo dashboard update {slug} --visibility private

See REST API — Delete Dashboard for the API details.

Related Documentation¶

• Dashboard Framework Overview — What dashboards are and how to build them
• Dashboard Manifest Reference — Complete huitzo-dashboard.yaml specification
• Dashboard Loading Architecture — How Hub discovers and renders dashboard modules at runtime
• REST API — Dashboards — Dashboard API endpoints
• CLI Reference — Complete CLI command reference
• Private Registry & Access Control — Pack access control model (same pattern)