trackhome-react

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