A report is a folder of app/src/reports/ with a report.tsx in it. The folder’s name is the report’s address: app/src/reports/sales/ opens at /reports/sales. Adding the folder adds the report to the list. Nothing else needs changing.

You rarely write these files yourself. Ask Claude, and use this page to know what is possible.

app/src/reports/sales/
  report.tsx       the page: meta, page options, queries, components, dialog
  monthly.sql      a query: first line its -- title, $from and $to for the dates
app/src/metrics/metrics.ts   the named metrics, used by name on components

A report folder holds only report.tsx and .sql files. Any other file fails the check.

Anatomy#

-- Sales and orders per month
select to_char(sold_on, 'YYYY-MM') as month,
       sum(amount) as sales, count(*) as orders
from sales
where sold_on between $from and $to
group by 1

import { defineReport, query } from "~/components/report-kit/define"
import { Info, Rule, Rules, Sql, Technical } from "~/components/report-kit/info"

import monthly from "./monthly.sql?raw"

type Month = { month: string; sales: number; orders: number }

export default defineReport({
  meta: {
    title: "Sales",
    description: "Sales and orders per month.",
    connector: "postgres",
  },
  page: {
    info: () => (
      <>
        <Info>
          <Rules>
            <Rule id="sales" title="Sales">
              the order amount, including tax, by the day it was sold.
            </Rule>
          </Rules>
        </Info>
        <Technical>
          <Sql query="monthly" />
        </Technical>
      </>
    ),
  },
  queries: { monthly: query<Month>(monthly, { grain: "month" }) },
  components: (k) => [
    <k.Line
      key="sales"
      series="monthly"
      x="month"
      xFormat="month"
      y={{ sales: "Sales" }}
      title="Sales per month"
      info={{ what: "Sales per month.", rules: ["sales"], sql: ["monthly"] }}
    />,
  ],
})

defineReport takes four parts: meta (the report’s name), page (its options and the dialog), queries (each .sql file, by the name components read it under) and components (the page, top to bottom). The page itself holds no text: explanations go in the dialog.

meta#

Which connector a report reads: the one its meta.connector names; otherwise SILVI_CONNECTOR in app/.env; otherwise the only connector installed; otherwise csv. With more than one connector, each report names its own.

page#

A key the page does not take fails the type check.

Queries#

Each query is a .sql file in the folder, imported with ?raw and named in queries: queries: { monthly: query<Month>(monthly) }. The name is how components read the result: series="monthly". Month is the row the query returns, one entry per column: components may name only those columns.

• Start the file with a -- comment line. It is the query’s title in the dialog; a file without one fails the check.
• Queries only read: they must start with select or with. The app refuses anything else.
• Write the SQL in your database’s own dialect. Claude picks the right one for the report’s connector.
• Every connector returns rows in one shape: numbers as numbers, dates as YYYY-MM-DD text, timestamps as YYYY-MM-DD HH:MM:SS.

Reshaping rows in code#

When the SQL cannot say it, a query can reshape its rows with reconstruct. It runs on the server after the rows are cut to the date filter’s range, and the components then read what it returns:

queries: {
  regions: query(regions, {
    reconstruct: (rows: Region[]) =>
      rows.map((r) => ({ region: r.region, perOrder: r.sales / r.orders })),
  }),
},

Here the components may name region and perOrder, and no longer sales. Prefer SQL when it can do the job: the dialog shows the SQL, not the code.

$from, $to and the date filter#

A query may use $from and $to, plus the param of any input the page declares. They are sent to the database as parameters, never pasted into the SQL text.

1. Every query runs once, over a wide window. $from is the first day of the month 23 months back, $to is today. The result is cached for ten minutes.
2. The rows are cut to the dates you pick, by the query’s grain. query<Month>(monthly, { grain: "month" }): each row needs a month column (2026-03). With "week", a week column (2026-W14). With "all", the default, nothing is cut.
3. So changing the dates runs no query. It is instant. A report opens on the first of the month a year ago through today.

A chart that should follow the date filter returns a week or month column and its query sets grain. With every query on "all" the filter changes nothing, so a report with no dates sets filterBar: false.

Dialects#

$from::date runs only on Postgres and Redshift. For a yes/no column a component reads, return 1 and 0: they work on all nine.

Components#

components is a function of k, the kit’s components typed by your queries, and returns the page’s components top to bottom: tiles, charts, tables, layout and inputs. Each reads one series by name, and the columns it names.

components: (k) => [
  <k.Kpis
    key="totals"
    series="totals"
    tiles={[
      { label: "Sales", value: "sales" },
      { label: "Orders", value: "orders" },
    ]}
  />,
  <k.CategoryBars key="bars" series="regions" x="region" value="sales" title="Sales by region" />,
],

Charts take half a row, so two sit side by side. Tiles, tables and sections take the whole row. Every component is on All components, with its props and an example.

A few props may read a value from the results instead of a fixed text: title, description, y, target, tooltip, reference, columns, groups, lines and segmentParams. Give them a function of the data: title={(d) => String(d.totals[0].label)} is the label column of the first row of totals.

The “(i)” dialog#

The “(i)” button in the report’s header opens its dialog: page.info, a function that returns its content. Every explanation of a report lives here, never on the page.

import { H2, Info, Rule, Rules, Sql, Technical } from "~/components/report-kit/info"

// in defineReport({ … })
page: {
  info: () => (
    <>
      <Info>
        <H2>The measures</H2>
        <Rules>
          <Rule id="sales" title="Sales">
            the order total after discounts, before tax and shipping.
          </Rule>
        </Rules>
      </Info>
      <Technical>
        <H2>The SQL</H2>
        <Sql query="regions" />
      </Technical>
    </>
  ),
},

All of these come from ~/components/report-kit/info:

The dialog ends with a “Data as of” line: when the report’s rows were read.

A component’s own “(i)”#

Each component can have its own “(i)” too, with info:

info={{ what: "Sales per month.", rules: ["sales"], sql: ["monthly"] }}

what is one line and required; rules picks rules from the dialog by id; sql lists query names. A <Rules as="table"> group lists the source tables, and a component’s “(i)” names the ones its SQL reads.

The checks#

Claude runs npm run lint after every change to a report. It checks three things:

A query that fails on the database shows its error on the page. To fix one, ask: “The Sales report fails the check. Fix it.”