Report DesignerDeveloper portal

Upgrading and versioning

Version numbers#

  • @rd/core, @rd/designer and @rd/server are released together with the same version number (semantic versioning: MAJOR.MINOR.PATCH). @rd/designer depends on exactly the same version of @rd/core. Upgrade all three together.
  • Patch releases fix bugs. Minor releases add features and keep compatibility. Major releases may change APIs. Their release notes list the required changes.

Template format#

Every template has "version": 1, the template format version. Version 1 is the only format so far. Later releases will keep reading version 1 templates, and the release notes will say if a new format version is introduced and how older templates are handled. Keep templates as opaque JSON, and don't depend on fields not described in @rd/core's Template type.

Rendering an old template with a new engine gives the same layout, except where a release note says a layout bug was fixed. Before a minor or major upgrade, re-render your production templates with their sample data and compare the PDFs (checklist).

Upgrade checklist#

  1. Read the release notes.
  2. Install the new tarballs in a test environment: designer, core, @rd/fonts (and @rd/fonts-cjk if you use it) and server together.
  3. Re-copy the fonts to your web server (the contents of @rd/fonts/fonts/ and @rd/fonts-cjk/fonts/, into one folder; they can change between releases), and for the standalone bundle also report-designer.worker.js, report-designer.help.js, report-designer.pdf.js and report-designer.pdf-worker.js. Use a versioned path to avoid stale caches.
  4. Render each production template with representative data and compare page counts and PDFs with the previous version. rd-render in a script works well for this (Command-line renderer).
  5. Check that X-Render-Warnings stays at 0 for your templates.
  6. Deploy the render service (rolling), then the front end.

Upgrading from 1.0 builds that bundled the fonts#

Earlier builds shipped the fonts inside @rd/designer (dist/fonts/) and @rd/core (fonts/). They are now separate packages: install @rd/fonts (required) and, for Chinese, Japanese and Korean documents, @rd/fonts-cjk. Change your copy step from node_modules/@rd/designer/dist/fonts to the two packages' fonts/ folders, copied into the same served folder. The @rd/designer/fonts/* export is gone. Release archives no longer contain npm/: the npm packages are in the separate reportdesigner-sdk-<version> download.