Documentation

Dashboards Overview

Define and deploy dashboards from TypeScript files

Dashboards live in analytics/dashboards/*.ts and are compiled byrealanalytics build into JSON for deployment.

Minimum dashboard config

import { defineDashboard, controls, widget } from '@realanalytics/sdk'

export default defineDashboard({
  id: 'overview',
  title: 'Overview',
  defaultDateRange: 'last_30_days',
  controls: [
    controls.dateRange({ editable: true }),
  ],
  widgets: [
    widget.metric({
      id: 'pageviews',
      label: 'Pageviews',
      event: '$pageview',
      aggregation: 'count',
    }),
  ],
})

DashboardConfig fields

Field	Type	Description
`id`	string	Dashboard slug/identifier
`title`	string	Display title
`defaultDateRange`	DateRangePreset	Initial date preset
`controls`	ControlConfig[]	Top-level UI controls
`widgets`	WidgetConfig[]	Rendered cards/charts

Date range presets

'today' | 'yesterday' | 'last_7_days' | 'last_30_days' | 'last_90_days'
| 'this_month' | 'last_month' | 'this_quarter' | 'this_year'

Controls

controls: [
  controls.dateRange({ editable: true }),
  controls.compare({ editable: true, enabled: true }),
  controls.filter({ editable: true }),
]

Controls decide what viewers may change without a code change. enabled(default true) turns a capability on or off; editable decides whether viewers can change it.

Control	Enabled and editable	Not editable or disabled
`dateRange`	Date range picker	Fixed `defaultDateRange` label; saved views can't change it
`filter`	Exploration filter, saved-view filters and chart drilldown	None of these; only code-defined filters apply
`compare`	Comparisons on, with a Compare toggle	Not editable: comparisons on, no toggle. Disabled: no comparison queries or overlays

A control you don't declare keeps its default: the date range and exploration filter are editable, and comparisons follow each widget's own settings (for example timeSeries.comparison or breakdown.showComparison) without a toggle. controls: [] therefore means "all defaults". Declare a control to lock or disable it.

Project structure

analytics/
├── events.ts
└── dashboards/
    ├── overview.ts
    ├── marketing.ts
    └── product.ts

Deploy changes