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:
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.
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:
-
Keep the types in
src/data/demo/types.ts. Move them to your own file, such assrc/api/types.ts, and change them to match your API. - Fetch the data in the page instead of importing it.
-
Show a
Skeletonwhile it loads and anEmptyStateorAlertif it fails. - 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/:
VITE_API_URL=https://api.example.com
Then write a hook that loads JSON from your API:
// 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:
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:
-
In
src/pages/auth/SignIn.tsx, replace the body ofsubmitwith a call to your service. - Keep the signed-in user in a React context, or in your data library.
-
To protect pages, check the user in
Shellinsrc/App.tsx. If there is no user and the page is not in theauth/group, return<Navigate to="/auth/sign-in" replace />.
// 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.