사용법

npm i @freereportjs/core

import { createViewer } from '@freereportjs/core';
import '@freereportjs/core/styles.css';

const definition = await fetch('/reports/sales.json').then(r => r.json());

const viewer = createViewer(document.getElementById('viewer'), {
  definition,
  data: { rows },     // detail rows; other keys are usable in expressions
  lang: 'ko',
});
// <div id="viewer" style="height: 720px"></div>

{
  "name": "거래처별 매출",
  "page": { "size": "A4", "orientation": "portrait", "margins": 15 },
  "font": { "family": "Nanum Gothic", "size": 9 },
  "sort": ["customer", "date"],
  "bands": {
    "title": { "height": 14, "elements": [
      { "type": "text", "x": 0, "y": 0, "w": 180, "h": 10, "text": "거래처별 매출", "style": { "fontSize": 16, "bold": true } }
    ] },
    "columnHeader": { "height": 7, "elements": [
      { "type": "text", "x": 0, "y": 0, "w": 30, "h": 7, "text": "일자", "style": { "bold": true, "border": true } },
      { "type": "text", "x": 30, "y": 0, "w": 110, "h": 7, "text": "거래처", "style": { "bold": true, "border": true } },
      { "type": "text", "x": 140, "y": 0, "w": 40, "h": 7, "text": "금액", "style": { "bold": true, "border": true } }
    ] },
    "detail": { "height": 6, "elements": [
      { "type": "field", "x": 0, "y": 0, "w": 30, "h": 6, "expr": "date", "format": "yyyy-MM-dd", "style": { "border": true } },
      { "type": "field", "x": 30, "y": 0, "w": 110, "h": 6, "expr": "customer", "suppressRepeated": true, "style": { "border": true } },
      { "type": "field", "x": 140, "y": 0, "w": 40, "h": 6, "expr": "amount", "format": "#,##0", "style": { "border": true, "align": "right" } }
    ] },
    "summary": { "height": 8, "elements": [
      { "type": "text", "x": 0, "y": 1, "w": 180, "h": 7, "text": "합계 {sum(amount):#,##0}원 ({koreanAmount(sum(amount))})", "style": { "align": "right", "bold": true } }
    ] },
    "pageFooter": { "height": 8, "elements": [
      { "type": "text", "x": 0, "y": 2, "w": 180, "h": 5, "text": "{page} / {pages}", "style": { "align": "center" } }
    ] }
  }
}

"groups": [{
  "by": "region", "sort": "asc", "repeatHeader": true, "keepWithRows": 2,
  "header": { "height": 7, "elements": [
    { "type": "text", "x": 0, "y": 0, "w": 180, "h": 7, "text": "■ {region} ({count()}건)", "style": { "bold": true } }
  ] },
  "footer": { "height": 7, "elements": [
    { "type": "text", "x": 0, "y": 0, "w": 140, "h": 7, "text": "{region} 소계", "style": { "align": "center" } },
    { "type": "field", "x": 140, "y": 0, "w": 40, "h": 7, "expr": "sum(amount)", "format": "#,##0", "style": { "align": "right" } }
  ] }
}],
"pageFooter": { "height": 7, "elements": [
  { "type": "text", "x": 0, "y": 1, "w": 180, "h": 6, "text": "이 페이지 소계 {sum(amount, 'page'):#,##0}원 · 누계 {sum(amount, 'report'):#,##0}원" }
] }

"styles": {
  "th": { "bold": true, "align": "center", "background": "#eef1f6", "border": "0.2 solid #8a94a6" },
  "num": { "align": "right", "border": { "bottom": "0.15 solid #b9c1cd" } }
},
"bands": { "detail": { "height": 6, "elements": [
  { "type": "field", "x": 140, "y": 0, "w": 40, "h": 6, "expr": "amount", "format": "#,##0", "styleName": "num", "style": { "bold": true } }
] } }

price * qty                         arithmetic
amount >= params.minAmount           comparison with a parameter
customer.name ?? '(미지정)'           member access and fallback
qty > 10 ? '대량' : '일반'             condition
sum(amount)                          aggregate over the band's scope
sum(amount, 'page')                  page subtotal
sum(amount) / sum(amount, 'report')  share of the grand total
format(date, 'yyyy년 M월 d일 (ddd)')  2026년 10월 15일 (목)
koreanAmount(1230000)                일금 일백이십삼만원정
bizNo('7928703276')                  792-87-03276
{page} / {pages}                     page x / y in a text template

// definition.params: { from: { label: '시작일', type: 'date', required: true },
//                      region: { label: '지역', type: 'select', options: [{ value: '' , label: '전체' }, { value: '서울' }] } }
createViewer(el, {
  definition,
  paramsOpen: true,
  fetchData: params => fetch('/api/sales?' + new URLSearchParams(params)).then(r => r.json()),
});

"detail": { "height": 38, "columns": 3, "columnGap": 3, "elements": [
  { "type": "field", "x": 2, "y": 2, "w": 36, "h": 6, "expr": "name", "style": { "bold": true } },
  { "type": "barcode", "x": 40, "y": 2, "w": 18, "h": 18, "expr": "'https://example.com/a/' + assetNo", "format": "qr", "ecc": "M" },
  { "type": "barcode", "x": 2, "y": 24, "w": 56, "h": 11, "expr": "assetNo", "format": "code128" }
] }

{ "type": "chart", "x": 0, "y": 16, "w": 110, "h": 60, "chartType": "bar", "title": "지역별 매출",
  "source": "groupSum(rows, 'region', 'amount')", "category": "region",
  "series": [{ "expr": "amount", "label": "매출" }], "format": "#,##0" },
{ "type": "table", "x": 0, "y": 20, "w": 180, "h": 20, "source": "items", "altBackground": "#fafbfd",
  "columns": [{ "header": "품목", "expr": "name" }, { "header": "수량", "expr": "qty", "width": 20, "align": "right" },
              { "header": "금액", "expr": "qty * price", "width": 40, "format": "#,##0", "sum": true }] },
{ "type": "crosstab", "x": 0, "y": 0, "w": 180, "h": 50, "rowKey": "region", "columnKey": "category",
  "value": "amount", "aggregate": "sum", "format": "#,##0", "corner": "지역 / 품목군" }

"watermark": [
  { "text": "{params.user} · {format(now(), 'yyyy-MM-dd HH:mm')} 출력", "repeat": true, "opacity": 0.07, "fontSize": 10, "gap": 40 },
  { "text": "사 본", "fontSize": 110, "color": "#c8102e", "pages": "all" }
],
"emboss": { "text": "(주)세컨드코리아 대표이사 직인 ·", "centerText": "인증", "x": 140, "y": 240, "w": 34 }

import { createDesigner } from '@freereportjs/core';
import '@freereportjs/core/styles.css';

const designer = createDesigner(document.getElementById('designer'), {
  definition,               // leave out to start with a blank report
  data: { rows },           // sample data for the field list and the preview
  lang: 'ko',
  onChange: def => localStorage.setItem('draft', JSON.stringify(def)),
  onSave: def => fetch('/api/reports/sales', { method: 'PUT', body: JSON.stringify(def) }),
});
designer.setMode('preview');      // 'design' | 'preview' | 'json'
const json = designer.getDefinition();

import { createReport } from '@freereportjs/core';

const report = createReport(definition, { rows });
await report.ready();                    // wait for web fonts, then lay out

await report.print();                    // browser print at the paper size
const pdf = await report.toPdf();        // Blob, fonts embedded
const form = await report.toXlsx('form'); // merged cells and borders, like the printout
const data = await report.toXlsx('data'); // one row per record
await report.download('pdf', '매출 보고서'); // or save directly

import { registerFont } from '@freereportjs/core';

registerFont('Malgun Gothic', {
  css: '/fonts/malgun.css',          // @font-face rules for screen and print (optional)
  normal: '/fonts/malgun.ttf',       // TrueType for the PDF (URL or Uint8Array)
  bold: '/fonts/malgunbd.ttf',
});
// then: "font": { "family": "Malgun Gothic" } or "style": { "fontFamily": "Malgun Gothic" }

// Node 20+, Deno or Bun — no browser needed
import { writeFile } from 'node:fs/promises';
import { loadFonts, renderPdf, renderXlsx } from '@freereportjs/core';

const fonts = await loadFonts(['Nanum Gothic']);        // TTF bytes (or read your own files)
const pdf = await renderPdf(definition, { rows }, { fonts, params: { user: 'batch' } });
await writeFile('sales.pdf', pdf);
await writeFile('sales.xlsx', await renderXlsx(definition, { rows }, { fonts, mode: 'form' }));

createViewer(el, {
  definition, data,
  pdfSecurity: {
    userPassword: '1234',                      // asked when the PDF is opened (omit: opens freely)
    permissions: { print: true, copy: false, modify: false },
  },
});

createViewer(el, {
  definition, data, params: { user: '홍길동' },
  // e = { kind: 'print' | 'pdf' | 'xlsx' | 'xlsx-data' | 'csv', report, pages, rows, params, fileName }
  onOutput: async e => {
    const res = await fetch('/api/output-log', { method: 'POST', body: JSON.stringify(e) });
    return res.ok;   // false cancels the print or download
  },
});

import { setLicenseKey } from '@freereportjs/core';

setLicenseKey('FR1.eyJkb21haW5zIjpb...');   // once, before creating viewers
// or: createViewer(el, { definition, data, licenseKey: 'FR1.eyJkb21haW5zIjpb...' })