Dashboard Manifest

dashboards manifest configuration huitzo-dashboard.yaml

Dashboard Manifest

Every Huitzo Dashboard requires a huitzo-dashboard.yaml manifest file that defines metadata, pack dependencies, pricing, and deployment configuration. This file lives at the root of your dashboard project.

Manifest Files: Dashboards use huitzo-dashboard.yaml. Intelligence Packs use huitzo.yaml. See Pack Manifest for pack configuration.

Quick Example

dashboard:
  name: "claims-dashboard"
  namespace: "claims"
  version: "1.0.0"
  description: "Claims management dashboard"
  visibility: "organization"
  author: "Acme Insurance"
  license: "proprietary"

pack_dependencies:
  - scope: "@acme"
    name: "claims-processor"
    version: ">=2.0.0 <3.0.0"
    required: true
  - scope: "@huitzo"
    name: "analytics"
    version: "*"
    required: false

pricing:
  model: "subscription"
  price: 29
  billing_period: "monthly"
  trial_days: 14

build:
  framework: "react"
  node_version: ">=20.0.0"
  build_command: "npm run build"
  output_directory: "dist"
  entry_point: "main.js"

deployment:
  hosting: "huitzo-cdn"
  cdn:
    subdomain: "claims"

metadata:
  homepage: "https://acme.com/claims-dashboard"
  keywords: ["claims", "insurance", "management"]
  category: "business"
  screenshots:
    - url: "https://cdn.acme.com/screenshot1.png"
      caption: "Main dashboard view"
    - url: "https://cdn.acme.com/screenshot2.png"
      caption: "Claims detail page"

File Structure

The manifest uses YAML format with these main sections:

Section Required Description
dashboard ✅ Yes Core dashboard metadata
pack_dependencies ✅ Yes Required Intelligence Packs
pricing ❌ No Marketplace pricing
build ❌ No Build configuration
deployment ❌ No Deployment settings
metadata ❌ No Additional metadata

Dashboard Section

The dashboard section defines core metadata about your dashboard.

Required Fields

dashboard:
  name: "my-dashboard"           # Unique identifier (kebab-case)
  namespace: "mydash"            # Short namespace (lowercase)
  version: "1.0.0"               # Semantic version
  description: "Dashboard for managing widgets"

Optional Fields

dashboard:
  # ... required fields ...

  visibility: "organization"     # public | unlisted | organization | private
  author: "Your Name"            # Author or company
  license: "MIT"                 # License identifier
  min_sdk_version: "1.0.0"       # Minimum Dashboard SDK version

Field Reference

Field Type Required Default Description
name string ✅ - Unique dashboard identifier (kebab-case)
namespace string ✅ - Short namespace (lowercase, no dashes)
version string ✅ - Semantic version (MAJOR.MINOR.PATCH)
description string ✅ - Short description (max 200 chars)
visibility enum ❌ organization Access control level
author string ❌ - Author name or organization
license string ❌ proprietary License identifier
min_sdk_version string ❌ 1.0.0 Minimum Dashboard SDK version

Visibility Levels

Level Description Discovery Access
public Available to all users Searchable, browsable No access grant required
unlisted Hidden from discovery Not searchable Requires dashboard link or ID
organization Requires explicit access Org members only Must have DashboardAccessGrant
private Only available to owner Owner only Owner organization only

Pack Dependencies Section

The pack_dependencies section declares which Intelligence Packs your dashboard consumes.

pack_dependencies:
  - scope: "@acme"
    name: "claims-processor"
    version: ">=2.0.0 <3.0.0"
    required: true

  - scope: "@huitzo"
    name: "analytics"
    version: "*"
    required: false

  - scope: "@acme"
    name: "notifications"
    version: "^1.0.0"
    required: false

Dependency Field Reference

Field Type Required Description
scope string ✅ Pack scope (e.g., @acme, @huitzo)
name string ✅ Pack name (kebab-case)
version string ✅ Semver range or * for any
required bool ❌ Whether pack must be installed (default: true)

Version Specifiers

Specifier Example Description
Exact 1.0.0 Exactly this version
Range >=1.0.0 <2.0.0 Version within range
Caret ^1.0.0 Compatible with 1.x.x
Tilde ~1.0.0 Compatible with 1.0.x
Any * Any version

Required vs Optional Dependencies

Required dependencies (required: true): - Dashboard won't install until user has the pack - Validation fails if pack is missing - User is prompted to install missing packs

Optional dependencies (required: false): - Dashboard installs without the pack - Features using the pack degrade gracefully - Use SDK to check if pack is available:

const { isPackInstalled } = useHuitzo();

if (isPackInstalled('@huitzo/analytics')) {
  // Show analytics features
}

Pricing Section

The pricing section configures marketplace pricing. Same models as Intelligence Packs.

Basic Pricing

pricing:
  model: "one-time"
  price: 99

Subscription Pricing

pricing:
  model: "subscription"
  price: 29
  billing_period: "monthly"
  trial_days: 14

Usage-Based Pricing (v2.5+)

pricing:
  model: "usage"
  per_session: 0.10       # Per user session
  monthly_minimum: 10

Pricing Models

Model Description Best For
one-time Pay once, access forever Tools, utilities
subscription Recurring payment SaaS products
usage Pay per session High-volume apps
free No charge (price: 0) Open source, demos

Pricing Field Reference

Field Type Required Default Description
model enum ❌ one-time Pricing model
price int ❌ 0 Price in USD
currency string ❌ usd Currency code
billing_period enum ❌ monthly For subscriptions: monthly, annual
trial_days int ❌ 0 Free trial period (0-30)
per_session float ❌ - Per-session price (usage model)
monthly_minimum float ❌ 0 Minimum monthly charge (usage model)

Pricing Validation Rules

These rules apply to both dashboards and packs (unified pricing model):

Rule Requirement
Minimum paid price $5 USD (prevents race-to-bottom)
Maximum price $10,000 USD
Trial days 0-30 days for subscriptions
Per-session $0.001 - $100 USD

Revenue Split

See Billing Reference for complete revenue split details.

Annual Revenue Platform Fee Developer Keeps
$0 - $5,000 0% 100%
$5,001 - $50,000 20% 80%
$50,001+ 10% 90%

Build Section

The build section configures how your dashboard is built.

build:
  framework: "react"
  node_version: ">=20.0.0"
  build_command: "npm run build"
  output_directory: "dist"
  entry_point: "main.js"
  env_prefix: "VITE_"          # Environment variable prefix

Build Field Reference

Field Type Required Default Description
framework enum ❌ react Framework: react, vue, svelte, angular, vanilla
node_version string ❌ >=18.0.0 Required Node.js version
build_command string ❌ npm run build Command to build the dashboard
output_directory string ❌ dist Build output directory
entry_point string ❌ main.js ESM module entry point (Vite library mode output)
env_prefix string ❌ VITE_ Environment variable prefix

Framework Support

Framework Status Template Command
React ✅ Supported huitzo dashboard new --template react
Vue 📋 Planned -
Svelte 📋 Planned -
Angular 📋 Planned -
Vanilla ✅ Supported huitzo dashboard new --template vanilla

Deployment Section

The deployment section configures where and how your dashboard is hosted.

Huitzo Hub (Default)

deployment:
  hosting: "huitzo-hub"
  hub:
    slug: "claims-dashboard"      # hub.huitzo.com/d/claims-dashboard

Self-Hosted Hub

deployment:
  hosting: "self-hosted"
  self_hosted:
    hub_url: "https://hub.company.com"
    slug: "claims-dashboard"      # hub.company.com/d/claims-dashboard
    api_url: "https://hub.company.com/api"

Deployment Field Reference

Field Type Required Default Description
hosting enum ❌ huitzo-hub Hosting type: huitzo-hub, self-hosted
hub.slug string ❌ (from name) Dashboard slug for Hub URL
self_hosted.hub_url string ❌ - Self-hosted Hub URL
self_hosted.slug string ❌ (from name) Dashboard slug
self_hosted.api_url string ❌ - Huitzo API endpoint

See Deployment Guide for complete setup instructions.

Metadata Section

Additional metadata for discoverability and documentation.

metadata:
  homepage: "https://acme.com/claims-dashboard"
  repository: "https://github.com/acme/claims-dashboard"
  documentation: "https://docs.acme.com/claims-dashboard"
  changelog: "https://github.com/acme/claims-dashboard/releases"
  keywords:
    - "claims"
    - "insurance"
    - "management"
  category: "business"
  screenshots:
    - url: "https://cdn.acme.com/screenshot1.png"
      caption: "Main dashboard"
    - url: "https://cdn.acme.com/screenshot2.png"
      caption: "Claims list"
  video_url: "https://youtube.com/watch?v=..."

Category Options

Category Description
business Business tools, CRM, management
analytics Data visualization, reporting
productivity Personal productivity, tasks
finance Financial dashboards, accounting
marketing Marketing dashboards, campaigns
operations Operations, monitoring
developer Developer tools, admin panels
other Uncategorized

Validation

The CLI validates your manifest before building:

huitzo dashboard validate

Validation Rules

  1. Required fields - All required fields must be present
  2. Naming conventions - Names follow kebab-case rules
  3. Version format - Version is valid semver
  4. Pack dependencies - Referenced packs exist
  5. Subdomain uniqueness - CDN subdomain is available
  6. Build configuration - Build command and output are valid

Common Validation Errors

❌ Error: dashboard.name must be kebab-case
   Found: "MyDashboard"
   Expected: "my-dashboard"

❌ Error: Pack dependency not found
   Pack: @acme/nonexistent-pack
   Fix: Verify pack name and scope

❌ Error: CDN subdomain already taken
   Subdomain: "analytics"
   Fix: Choose a unique subdomain

Complete Example

# huitzo-dashboard.yaml - Insurance Claims Dashboard

dashboard:
  name: "claims-management"
  namespace: "claims"
  version: "2.1.0"
  description: "Complete claims management dashboard for insurance companies"
  visibility: "organization"
  author: "Acme Insurance Tech"
  license: "proprietary"
  min_sdk_version: "1.0.0"

pack_dependencies:
  - scope: "@acme"
    name: "claims-processor"
    version: ">=2.0.0 <3.0.0"
    required: true

  - scope: "@acme"
    name: "document-analyzer"
    version: "^1.5.0"
    required: true

  - scope: "@huitzo"
    name: "analytics"
    version: "*"
    required: false

  - scope: "@huitzo"
    name: "notifications"
    version: ">=1.0.0"
    required: false

pricing:
  model: "subscription"
  price: 99
  billing_period: "monthly"
  trial_days: 14

build:
  framework: "react"
  node_version: ">=20.0.0"
  build_command: "npm run build"
  output_directory: "dist"
  entry_point: "main.js"

deployment:
  hosting: "huitzo-cdn"
  cdn:
    subdomain: "claims-mgmt"

metadata:
  homepage: "https://acme-insurance.com/claims-dashboard"
  documentation: "https://docs.acme-insurance.com/claims"
  keywords:
    - "claims"
    - "insurance"
    - "management"
    - "processing"
  category: "business"
  screenshots:
    - url: "https://cdn.acme.com/claims-main.png"
      caption: "Claims overview dashboard"
    - url: "https://cdn.acme.com/claims-detail.png"
      caption: "Claim detail view"
    - url: "https://cdn.acme.com/claims-analytics.png"
      caption: "Analytics dashboard"