React report designer

Three files, and one of them is your brand.

There is no project template to scaffold and no configuration file. You describe your data, you mount a component, and later — anywhere, in any process — you turn a saved design plus real data into a document.

1. 01

   Declare what exists

   A DataSource is your half of the contract: the fields, their types and what to call them on screen. The designer knows nothing else about your domain — no table names, no endpoints, no records. Users pick from what you declared, and what they save references those fields by path.

   data-sources.ts React

   import type { DataSource } from "@broadpaper/core";
   
   export const dataSources: DataSource[] = [
     {
       id: "inspection",
       label: "Inspection",
       schema: {
         reference: { type: "string", label: "Reference" },
         carriedOut: { type: "date", label: "Carried out" },
         passed: { type: "boolean", label: "Passed" },
         sitePhoto: { type: "image", label: "Site photograph" },
         findings: {
           type: "array",
           label: "Findings",
           itemSchema: {
             type: "object",
             fields: {
               item: { type: "string", label: "Item" },
               severity: { type: "string", label: "Severity" },
               cost: { type: "currency", label: "Estimated cost", currency: "GBP" }
             }
           }
         }
       }
     }
   ];

   Declaring currency rather than number is what lets the picker offer “£12,345.67” as a one-click format and makes a column of totals format correctly with nobody writing a pipe. An array of objects also exposes each field as a list, which is what a table binds to and what sum() takes.

2. 02

   Mount the designer

   ReportDesignerProps mirrors the framework-neutral ReportDesignerOptions, so everything in the API reference is a prop. onChange fires on every edit; onSave is yours and is what the Save button and ⌘S call.

   TemplateEditor.tsx React

   import { useState } from "react";
   import { ReportDesigner } from "@broadpaper/react";
   import type { ReportTemplate } from "@broadpaper/core";
   import { dataSources } from "./data-sources";
   import { sampleData } from "./sample-data";
   import { brand } from "./themes";
   
   export function TemplateEditor({ initial }: { initial?: ReportTemplate }) {
     const [draft, setDraft] = useState<ReportTemplate | undefined>(initial);
   
     return (
       // The designer fills its container, so the container needs a height.
       <div style={{ height: "100vh" }}>
         <ReportDesigner
           template={draft}
           dataSources={dataSources}
           sampleData={sampleData}
           theme={brand}
           saveDescription="Saved to this workspace."
           onChange={setDraft}
           onSave={async (template) => {
             const res = await fetch(`/api/templates/${template.id}`, {
               method: "PUT",
               headers: { "content-type": "application/json" },
               body: JSON.stringify(template)
             });
             // Throwing is how you get "Save failed" with your own message
             // in the toolbar, instead of a silent no-op.
             if (!res.ok) throw new Error(`Could not save (${res.status})`);
           }}
         />
       </div>
     );
   }

3. 03

   Render the document

   One call takes the saved JSON and real data to a vector PDF. It is the same function in a browser, in a Node worker and in a container, and it returns the page count with the bytes.

   render.ts Browser or Node

   import { renderPdfPaginated } from "@broadpaper/forme";
   import { createRegistry } from "@broadpaper/blocks";
   import type { ReportData, ReportTemplate } from "@broadpaper/core";
   import { dataSources } from "./data-sources";
   import { brand } from "./themes";
   
   export async function renderInspection(template: ReportTemplate, data: ReportData) {
     const { pdf, pages, warnings } = await renderPdfPaginated({
       template,                   // the JSON your user designed
       data,                       // this inspection, from your database
       theme: brand,               // the tenant's brand
       dataSources,
       registry: createRegistry(), // plus your own blocks: createRegistry([myBlock])
       metadata: { title: "Site inspection", author: brand.name }
     });
     if (warnings.length) console.warn("[broadpaper]", warnings);
     return { pdf, pages };        // pdf is a Uint8Array
   }

Where the same template becomes a file.

The page breaks are decided by BroadPaper's own paginator before any backend draws anything, so the answer to “where do we render?” is a deployment question rather than a fidelity one.

Six things worth knowing before you wire it up.