Defining Dashboards

Patterns for authoring dashboards as code

Start with one dashboard file

// analytics/dashboards/overview.ts
import { defineDashboard, controls, widget } from '@realanalytics/sdk'

export default defineDashboard({
  id: 'overview',
  title: 'Overview',
  defaultDateRange: 'last_30_days',
  controls: [
    controls.dateRange({ editable: true }),
    controls.filter({ editable: true }),
  ],
  widgets: [
    widget.metric({
      id: 'signups',
      label: 'Signups',
      event: 'signup_completed',
      aggregation: 'count',
    }),
    widget.timeSeries({
      id: 'traffic',
      title: 'Traffic',
      event: '$pageview',
      metric: 'count',
      chartType: 'area',
      layout: { colSpan: 8 },
    }),
    widget.breakdown({
      id: 'sources',
      title: 'Traffic Sources',
      event: '$pageview',
      defaultBreakdown: '$referrer_domain',
      metric: 'count',
      layout: { colSpan: 4 },
    }),
  ],
})

Use one dashboard per business question

  • overview.ts: high-level KPIs
  • acquisition.ts: channels + campaigns
  • activation.ts: onboarding funnels
  • retention.ts: repeat usage and cohorts

Prefer widget builders

Use widget.metric(), widget.timeSeries(), etc. instead of raw objects to get defaults and stronger typing.

Lean on built-in events first

You can build useful dashboards immediately with $pageview,$click, $form_submit, and related built-ins, then layer in custom events from analytics/events.ts.

Layout tips

  • Use layout.colSpan (1-12) to control width
  • Keep primary charts in wider spans (6-12)
  • Use metrics in smaller spans (3-4)
  • Group related widgets in the same row

Deployment workflow

# 1) Validate and compile
npx realanalytics build

# 2) Push to your project
npx realanalytics deploy

Build output lands in .realanalytics/events.json and.realanalytics/dashboards.json, then deploy uploads both.

Current runtime limits

  • Dashboard filters are translated as a single condition in current query flow
  • Funnel querying currently supports first two steps for live data responses

Next Steps