Skip to content
DocsBuild
Build

Demo data and your API

Every name and number in the demo comes from a few JSON files. This page explains how the demo data is organized and how to replace it with data from your own API.

#The demo world

The demo shows Hearth, the control system of a twelve-story building with homes and offices. A small property team runs it. All people, companies, numbers and dates are invented.

The data is consistent across pages. A device on the overview is the same device, with the same readings, in the device list and on the device page.

#The data files

All demo data is in src/data/demo/:

File What is inside
building.json The building: name, address, floors, sites, weather, comfort score
energy.json Today's use, hourly use, monthly cost, meters, solar and battery, tariffs, reports
climate.json Zones, scenes, the weekly schedule, air quality
devices.json Devices, device types, gateways, firmware, alerts
work.json Work orders, the board, preventive maintenance, vendors, parts
access.json The access feed, doors, credentials, visitors, cameras
residents.json Residents, units, leases, requests, announcements, amenities, bookings
workspace.json Inbox, chat, calendar events, notes, audit log
account.json Profile, sessions, integrations, billing
team.json The property team
counters.json The numbers on the sidebar badges
types.ts TypeScript types for every file
index.ts Exports everything, plus NOW, FEATURED and lookup helpers

Pages import from the folder, never from a single JSON file:

TSX
import { devices, energy, NOW, personById } from '@/data/demo';

#The demo clock

Dates such as "4 hours ago" are measured from NOW, a fixed time in index.ts, not from the real clock. This keeps the demo the same every day.

TSX
import { NOW } from '@/data/demo';
import { relative } from '@/lib/format';

relative(order.created, NOW); // "4 hours ago"

In your app, use the real time instead: relative(order.created, new Date()).

#Lookup helpers

index.ts also exports small helpers that find one record by its ID:

Helper Returns
personById(id) A team member. Falls back to the first person.
residentById(id) A resident, or undefined
deviceById(id) A device, or undefined
orderById(id) A work order, or undefined
meterById(id) A meter, or undefined
zoneById(id) A climate zone, or undefined
sceneById(id) A scene, or undefined

FEATURED holds the ID of the record each detail page shows, for example FEATURED.device is 'DEV-1043'.

#Formatting helpers

src/lib/format.ts formats numbers and dates with the browser's Intl API, in the language set on <html lang>. Use these instead of writing numbers by hand, so every page looks the same.

Function Example input Output
num(value, digits?) num(1240) 1,240
unit(value, symbol, digits?) unit(38, 'kW') 38 kW
currency(value, code?, digits?) currency(1240) $1,240.00
percent(value, digits?) percent(71) 71%. Takes 0 to 100, not 0 to 1.
temp(value, digits?) temp(21.5) 21.5°
delta(value, digits?) delta(-8) -8%. Always shows the sign.
bytes(value) bytes(3355443) 3.2 MB
date, dateShort, dateLong, monthYear, weekday, time, dateTime an ISO string or Date Dates in different lengths
relative(value, now) two dates 4 hours ago, in 2 days
initials(name) initials('Riley Amara') RA
cx(...classes) cx('am-btn', on && 'is-on') Joins class names and skips empty ones

#Connect your own API

The template has no back end. Pages read the JSON files directly. When you connect your API, the usual path is:

  1. Keep the types in src/data/demo/types.ts. Move them to your own file, such as src/api/types.ts, and change them to match your API.
  2. Fetch the data in the page instead of importing it.
  3. Show a Skeleton while it loads and an EmptyState or Alert if it fails.
  4. When no page uses a demo file any more, delete it.

Here is a small, complete example. First, put your API address in a file named .env.local in template/:

Terminal
VITE_API_URL=https://api.example.com

Then write a hook that loads JSON from your API:

TSX
// src/hooks/useApi.ts
import { useEffect, useState } from 'react';

const BASE = import.meta.env.VITE_API_URL as string;

export function useApi<T>(path: string): { data: T | null; error: Error | null; loading: boolean } {
  const [data, setData] = useState<T | null>(null);
  const [error, setError] = useState<Error | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const controller = new AbortController();
    setLoading(true);
    fetch(`${BASE}${path}`, { signal: controller.signal, credentials: 'include' })
      .then((res) => {
        if (!res.ok) throw new Error(`Request failed: ${res.status}`);
        return res.json() as Promise<T>;
      })
      .then((json) => {
        setData(json);
        setError(null);
      })
      .catch((err: unknown) => {
        if (!controller.signal.aborted) setError(err as Error);
      })
      .finally(() => {
        if (!controller.signal.aborted) setLoading(false);
      });
    return () => controller.abort();
  }, [path]);

  return { data, error, loading };
}

And use it in a page. This is the Meters list, reading from your API:

TSX
import { ListPage } from '@/components/patterns/ListPage';
import { Alert } from '@/components/ui/Alert';
import { Skeleton } from '@/components/ui/EmptyState';
import { useApi } from '@/hooks/useApi';
import type { Meter } from '@/data/demo';

export default function Meters(): React.JSX.Element {
  const { data, error, loading } = useApi<Meter[]>('/meters');

  if (loading) return <Skeleton height="320px" />;
  if (error) return <Alert tone="bad" title="Meters could not load">{error.message}</Alert>;

  return (
    <ListPage
      title="Meters"
      rows={data ?? []}
      columns={columns}
      rowKey={(m) => m.id}
      searchIn={(m) => `${m.id} ${m.name}`}
    />
  );
}

#Sign in and protected pages

The sign-in pages check their fields in the browser and then open the overview. To connect them to your login service:

  1. In src/pages/auth/SignIn.tsx, replace the body of submit with a call to your service.
  2. Keep the signed-in user in a React context, or in your data library.
  3. To protect pages, check the user in Shell in src/App.tsx. If there is no user and the page is not in the auth/ group, return <Navigate to="/auth/sign-in" replace />.
TSX
// src/App.tsx, inside Shell()
const user = useUser(); // your own hook
if (!user && !slug.startsWith('auth/') && !slug.startsWith('error/')) {
  return <Navigate to="/auth/sign-in" replace />;
}

Remember that checks in the browser only hide pages. Your API must check every request too.