Quick Start

Overview

This guide walks you through defining a simple report schema, binding data, and rendering the output to HTML. By the end, you will have a working report with a header, a detail band that iterates over items, and a footer.

Step 1: Define the schema

A report schema describes the structure, layout, and data bindings of your report. Here is a minimal schema with three bands:

const schema = {
  version: '1.0',
  type: 'report',
  page: {
    size: 'A4',
    orientation: 'portrait',
    margins: { top: 20, right: 20, bottom: 20, left: 20 },
  },
  bands: [
    {
      type: 'header',
      height: 60,
      components: [
        {
          type: 'text',
          position: { x: 20, y: 20, width: 200, height: 30 },
          content: 'Sales Report',
          fontSize: 24,
          fontWeight: 'bold',
        },
      ],
    },
    {
      type: 'detail',
      height: 30,
      dataBinding: 'items',
      components: [
        {
          type: 'text',
          position: { x: 20, y: 5, width: 200, height: 20 },
          content: '{{item.name}}',
          fontSize: 14,
        },
        {
          type: 'text',
          position: { x: 400, y: 5, width: 100, height: 20 },
          content: '{{formatCurrency(item.price, "USD")}}',
          fontSize: 14,
          textAlign: 'right',
        },
      ],
    },
    {
      type: 'footer',
      height: 40,
      components: [
        {
          type: 'text',
          position: { x: 20, y: 10, width: 300, height: 20 },
          content: 'Total items: {{count(items)}}',
          fontSize: 12,
          color: '#6b7280',
        },
      ],
    },
  ],
}

Step 2: Provide the data

The data object supplies values that the engine resolves at render time. The items array drives the detail band:

const data = {
  items: [
    { name: 'Widget A', price: 29.99 },
    { name: 'Widget B', price: 49.99 },
    { name: 'Widget C', price: 19.99 },
  ],
}

Step 3: Render the report

Use renderReport to produce the intermediate representation, then convert it to HTML:

import { renderReport, renderToHtml } from '@nextreport/engine'

const result = renderReport(schema, data)
const html = renderToHtml(result)

console.log(html)

The output is a self-contained HTML string with inline styles. The detail band renders once per item, producing three rows with the product name and formatted price.

What just happened?

1. Schema parsing — the engine validated the schema structure
2. Expression resolution — {{item.name}} and {{formatCurrency(...)}} were evaluated against the data
3. Band expansion — the detail band iterated over the items array, creating one row per element
4. Layout — components were positioned according to their position coordinates
5. HTML output — the intermediate representation was serialized to HTML

Next steps

• Your First Report — build a complete invoice with all band types
• Bands — learn about header, detail, footer, and planned band types
• Expressions — master the {{...}} expression syntax