trackhome-react

Embeddable trackhome analytics dashboard for React. Pass two props, get a live dashboard.

Tree-shakeable: pick your entry

Since v1.3.0 the package ships three entry points. Pick the one that matches your use case and the bundler drops everything else from your production bundle.

| Import path | Bundle (min) | What you get | |--------------------------|--------------|-----------------------------------------------------------------------| | trackhome-react/readonly | ~42 KB | View-only dashboard. No editor code at all. | | trackhome-react/editable | ~104 KB | Full in-browser editor (add / edit / drag / resize / AI agent / etc.) | | trackhome-react | ~104 KB | Alias for /editable. Kept so existing imports keep working. |

readonly is a strict subset of editable. If you render dashboards that are configured elsewhere (admin UI, server-side, etc.) and never need to edit them in the host page, import /readonly and you'll save ~60 KB minified.

v2.0.0 dropped the dedicated index.tsx barrel — the bare trackhome-react entry is now wired straight to /editable so existing imports keep compiling without a separate shim file. New code should pick /readonly or /editable explicitly. See "v2.0.0 migration" below.

Install

npm install trackhome-react

Quick start — read-only (recommended for production embeds)

import { TrackhomeDashboardView } from 'trackhome-react/readonly';

function App() {
  return (
    <TrackhomeDashboardView
      endpoint="YOUR_TRACKHOME_URL"
      authKey="ek_abc123..."
      uid="my-dashboard"
    />
  );
}

The component fetches its config (widgets, name, theme) from the server, renders the widgets, and refreshes on a timer. No editor UI is loaded — there is no way for a viewer to mutate the dashboard.

Quick start — editable (in-browser customization)

import { TrackhomeDashboard } from 'trackhome-react/editable';

function App() {
  return (
    <TrackhomeDashboard
      endpoint="YOUR_TRACKHOME_URL"
      authKey="ek_abc123..."
      uid="my-dashboard"
      editable                 // enables Edit / Add widget / drag / resize
      secretKey="..."          // admin SECRET_KEY — required to save edits
    />
  );
}

The editable component supports everything the readonly one does, plus:

• "+ Add widget" / "✎ Edit" / drag-to-reorder / resize / duplicate / remove
• Tab CRUD (add / rename / delete / reorder)
• Widget editor modal with three modes:
  • AI — natural-language prompt → spec
  • Visual — form editor for sources / measures / formulas / view
  • JSON — raw spec textarea
• Live preview (debounced) against the server
• Snapshot history modal (view + restore within 30-day TTL)

All mutations PATCH /e/<authKey>/<uid> and require the admin secretKey.

v2.0.0 migration (breaking)

v2.0.0 dropped the bare trackhome-react entry. Update imports to be explicit:

- import { TrackhomeDashboard } from 'trackhome-react';
+ import { TrackhomeDashboard } from 'trackhome-react/editable';

If you only render dashboards (no in-browser editing), prefer the smaller readonly bundle:

- import { TrackhomeDashboard } from 'trackhome-react';
+ import { TrackhomeDashboardView } from 'trackhome-react/readonly';

The . entry still resolves (it points at /editable) so existing code that imports from 'trackhome-react' continues to compile and bundle — but the barrel file is gone. New code should pick a subpath explicitly.

Props

TrackhomeDashboardView (readonly)

| Prop | Type | Required | Description | |---|---|---|---| | endpoint | string | Yes | Base URL of your trackhome instance | | authKey | string | Yes | Read-only embed key (NOT your secret key) | | uid | string | Yes | Unique dashboard identifier | | secretKey | string | No | Admin secret — only used to enrich per-widget filter autocomplete | | refreshInterval | number | No | Auto-refresh interval in seconds. Default: 30. Set 0 to disable. | | dateRange | { from?, to? } | No | Custom date range (YYYY-MM-DD). Defaults to last 7 days. Hides the UI picker when set. | | className | string | No | CSS class for the container |

TrackhomeDashboard (editable) adds

| Prop | Type | Required | Description | |---|---|---|---| | editable | boolean | No | Enable in-browser edit mode. Default: false. | | secretKey | string | No* | Admin SECRET_KEY. Required to save edits. If omitted and editable is true, the user is prompted on first Edit click (cached in localStorage). |

* Effectively required when editable is true — without it, every save returns 401.

Getting an authKey

1. Open your trackhome admin dashboard
2. Go to Embeds → New key
3. Create an embed dashboard (clone from existing or configure from scratch)
4. Copy the generated authKey + uid

The authKey is read-only — it can only read dashboard configs and aggregate analytics. It cannot access raw events, links, funnels, or admin operations.

Features

• Zero config: widget layout stored server-side, fetched by uid
• Tree-shakeable: pick /readonly (~42 KB) or /editable (~104 KB)
• Self-styled: inline CSS, no dependency on host app's CSS framework
• Light/dark theme: stored in the embed config, switchable
• All widget kinds: KPI, number grid, bar, line, area, pie, funnel, heatmap, sankey, timeline, table (via the declarative pipeline widget)
• Auto-refresh: polls for new data every 30s (configurable)
• Per-widget filter overlay: viewers can narrow a widget by extra tags (browser-only, not saved)
• Tab navigation: dashboards with multiple tabs get a chip strip
• Edit mode (/editable only): optional in-browser customization that saves back to server — drag, resize, AI agent, visual editor, JSON editor, snapshot history
• TypeScript: full type definitions included

License

MIT