Report

How plugins contribute to the global reports hub with AppRegistry.report.add, a nested report router, and API-backed report pages.

Overview

The shell owns the Reports section. Plugins register one page element during register() — typically a small hub with nested Routes for each report. Heavy aggregation stays on the backend; the frontend loads data via withApiMetadataFetchFn + React Query.

Register with AppRegistry.report.add({ pluginName, page })
page is usually a hub + nested <Routes> for individual reports
Sub-paths must be relative (no leading /)
Gate access with the same APIs used by report queries

1. Register with AppRegistry.report.add

In frontend/src/index.tsx, call AppRegistry.report.add inside PluginModule.register. Shape: { pluginName, page } where page is a ReactElement.

pluginName must equal module.metadata.json name
page is JSX (<MyModuleReports />), not the component type

TSXfrontend/src/index.tsx

import type { AppRegistryState, PluginModule } from "@quan-erp/shared-types";
import metadata from "../module.metadata.json" with { type: "json" };
import { MyModuleReports } from "./page/report";

const Plugin: PluginModule = {
  register(AppRegistry: AppRegistryState) {
    AppRegistry.report.add({
      pluginName: metadata.name,
      page: <MyModuleReports />,
    });
  },
};

export default Plugin;

2. Report hub + nested routes

When a plugin has multiple reports, build a landing hub (card grid) and nest Routes so deep links work. Sub-paths must be relative to the parent report route — use employees, not /employees.

Use react-router-dom <Routes> / <Route> for deep-linking
Index route = hub; child routes = individual reports
Localize titles and descriptions — do not hardcode user-facing strings in production plugins

TSXfrontend/src/page/report/index.tsx

import { Route, Routes, useNavigate } from "react-router-dom";
import { Page, PageContent, PageTitle } from "@quan-erp/shared-ui";
import metadata from "../../../module.metadata.json" with { type: "json" };
import { EmployeesReport } from "./employees-report";

const reportList = [
  {
    id: "employees",
    name: "Employees",
    description: "Headcount and status breakdown",
    path: "employees",
    element: <EmployeesReport />,
  },
];

export function MyModuleReports() {
  const navigate = useNavigate();

  return (
    <Routes>
      <Route
        index
        element={
          <Page pluginName={metadata.name}>
            <PageTitle>
              <span>Module reports</span>
            </PageTitle>
            <PageContent>
              <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 mt-4">
                {reportList.map((item) => (
                  <button
                    key={item.id}
                    type="button"
                    className="text-left border rounded-xl p-4 hover:shadow-md transition"
                    onClick={() => navigate(item.path)}
                  >
                    <div className="font-medium">{item.name}</div>
                    <div className="text-sm text-muted-foreground">
                      {item.description}
                    </div>
                  </button>
                ))}
              </div>
            </PageContent>
          </Page>
        }
      />
      {reportList.map((item) => (
        <Route key={item.path} path={item.path} element={item.element} />
      ))}
    </Routes>
  );
}

3. Data layer

Load report data through src/api with withApiMetadataFetchFn and React Query hooks (same Admin Axios & Query pattern). Keep heavy grouping/filtering on the backend.

Declare report endpoints in .api.ts; consume via .queries.ts
Pass requiredApis / Protected using the same API objects
Prefer server-side aggregates over shipping huge raw tables to the browser

4. Tables

Most reports use a table. DataTable is not exported from @quan-erp/shared-ui — use a local plugin DataTable (often under components/) built on shared-ui Table primitives, or copy the pattern from another plugin (e.g. hr).

TSXlocal DataTable

import { DataTable } from "../../components/DataTable";

// columns + rows from your report query hook
<DataTable columns={columns} data={rows} />

Critical rules

Register only in register() via AppRegistry.report.add
pluginName must match metadata.name
page is a ReactElement (JSX)
Nested report paths must be relative — no leading slash
Localize hub and report UI strings
Lazy-load heavy report pages when the hub lists many entries

Checklist

Create page/report hub with nested Routes
AppRegistry.report.add({ pluginName, page }) in register()
Wire report APIs with withApiMetadataFetchFn + React Query
Relative sub-paths; localize labels
Verify under Reports after quan-erp watch and install

Common failures

Report missing in hub — not registered, wrong pluginName, or plugin not installed
Blank nested page — path used a leading / or does not match Route path
Deep link 404 — missing nested <Routes> / index route
Permission errors — report UI not gated with the same requiredApis as the query
Huge payload / slow UI — aggregation done on the client instead of the backend