# Getting Started

## Requirements

- **Node.js** 18+ with npm
- **Vue 3** (if integrating in a Vue project)

## Installation

### npm (recommended)

```bash
npm install nexabase-report
```

### CDN (no install required)

```html
<script src="https://cdn.jsdelivr.net/npm/nexabase-report/dist/nexabase-report.umd.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report/dist/style.css">
```

## Register the Custom Element

### Vue 3

```vue
<script setup>
import { registerNexaReport } from 'nexabase-report';
registerNexaReport();
</script>

<template>
  <nexa-viewer
    :definition="reportDefinition"
    :data="reportData"
    :parameters="{ fechaDesde: '2024-01-01' }"
    skip-params-dialog
  />
</template>
```

### HTML / Vanilla JS

```html
<script>
  window.NexaReport.registerNexaReport();
</script>

<nexa-viewer id="viewer"></nexa-viewer>

<script>
  const viewer = document.getElementById('viewer');
  viewer.definition = { /* report definition JSON */ };
  viewer.data = [ /* data array */ ];
</script>
```

### React

```tsx
import { useEffect } from 'react';
import 'nexabase-report';

export function ReportViewer({ definition, data }) {
  useEffect(() => {
    window.NexaReport?.registerNexaReport();
  }, []);

  return <nexa-viewer ref={(el) => {
    if (el) {
      el.definition = definition;
      el.data = data;
    }
  }} />;
}
```

### Angular

```ts
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}
```

```html
<!-- component.html -->
<nexa-viewer
  [definition]="reportDef"
  [data]="reportData"
  [parameters]="params"
></nexa-viewer>
```

## Core Concepts

### Report Definition

A report is a JSON object that describes the layout, bands, elements, data sources, and styling.

```json
{
  "metadata": {
    "name": "Sales Report",
    "version": "1.0",
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "layout": {
    "page": {
      "format": "A4",
      "orientation": "portrait",
      "margins": { "top": 1.5, "right": 1.5, "bottom": 1.5, "left": 1.5 }
    },
    "bands": [
      {
        "id": "header",
        "type": "ReportHeader",
        "height": 80,
        "elements": [
          {
            "id": "title",
            "type": "Text",
            "x": 0,
            "y": 0,
            "width": 700,
            "height": 50,
            "content": "{{ReportName}}",
            "style": { "fontSize": "24px", "fontWeight": "bold" }
          }
        ]
      }
    ]
  },
  "dataSources": [
    { "id": "ds1", "collection": "sales", "alias": "main", "enabled": true }
  ]
}
```

### Bands (Report Model)

NexaReport uses a **banded report model** inspired by Stimulsoft/DevExpress:

| Band | When it renders |
|------|----------------|
| `ReportHeader` | Once, at the top of the first page |
| `PageHeader` | At the top of every page |
| `DataBand` | Once per data row |
| `DetailBand` | Nested detail for master-detail |
| `GroupHeader` | At the start of each group |
| `GroupFooter` | At the end of each group |
| `PageFooter` | At the bottom of every page |
| `ReportFooter` | Once, at the end of the last page |

### Expressions

Use `{{field}}` for field binding and `{[expression]}` for computed expressions:

```
{{clientName}}           → bound to data field
{[UPPER(clientName)]}    → uppercase
{[FORMATNUMBER(amount, 2)]}  → formatted number
{[IIF(total > 0, 'OK', 'ZERO')]}  → conditional
{[NOW()]}                → current date/time
```

See the [Expression Engine](/api/expression-engine) reference for all available functions.

## Next Steps

- [Quick Start](/guide/quick-start) — build your first report
- [Designer Guide](/guide/designer) — WYSIWYG report designer
- [Viewer Props](/reference/props) — all available viewer properties
- [Export Guide](/guide/export) — PDF, Excel, Word, CSV