Install

What you receive#

The npm packages in the SDK download:

All packages have the same version number. Always install matching versions: @rd/designer depends on exactly the same version of @rd/core, and @rd/core on the same version of @rd/fonts. Without @rd/fonts-cjk, Chinese, Japanese and Korean characters render as blank boxes and the designer's preview reports "CJK text needs @rd/fonts-cjk (not installed)".

Installing the front-end packages#

From the tarballs. List every tarball, because npm won't find the @rd packages on the public registry:

npm install ./vendor/rd-designer-1.0.0.tgz ./vendor/rd-core-1.0.0.tgz ./vendor/rd-fonts-1.0.0.tgz
npm install ./vendor/rd-fonts-cjk-1.0.0.tgz     # optional: Chinese, Japanese and Korean

This writes file: dependencies to package.json. Commit the tarballs (or store them in your artifact repository) so CI can install them.

From a private registry (recommended for teams). Publish the tarballs once to your npm-compatible registry (Artifactory, Nexus, Verdaccio, GitHub Packages, Azure Artifacts):

npm publish ./rd-fonts-1.0.0.tgz --registry https://npm.internal.example.com/
npm publish ./rd-fonts-cjk-1.0.0.tgz --registry https://npm.internal.example.com/
npm publish ./rd-core-1.0.0.tgz --registry https://npm.internal.example.com/
npm publish ./rd-designer-1.0.0.tgz --registry https://npm.internal.example.com/

Then map the @rd scope to that registry in your project's .npmrc, and install normally:

echo "@rd:registry=https://npm.internal.example.com/" >> .npmrc
npm install @rd/designer@1.0.0 @rd/fonts@1.0.0
npm install @rd/fonts-cjk@1.0.0                 # optional

What your web server must host#

The designer loads its fonts at runtime. When you bundle it with Vite, webpack, esbuild or the Angular CLI, your bundler doesn't copy them, so copy them to a served folder yourself:

Help needs no hosting. The user guide (pages, images and search index) is built into the component and renders inside its Help drawer, offline and without an iframe. In the npm (library) build, it is a lazy chunk your bundler emits automatically: about 4.6 MB raw, 3 MB gzip, downloaded only when a user first opens help.

Browsers download only what is used. A template that uses Arimo regular and bold fetches two font files of about 400 KB each. The 5–10 MB Chinese, Japanese and Korean fonts are fetched only when a text contains such characters. See Hosting fonts, help and the worker for the copy step in each build tool, CDN hosting and caching.

Note: With the npm (library) build, the preview worker and the help content are bundled automatically as lazy chunks, so there are no separate files to host. Import PDF uses the pdfjs-dist dependency (Mozilla's pdf.js, Apache-2.0), which your bundler also emits as lazy chunks: about 2 MB raw, 540 KB gzip, downloaded only when a user imports a PDF. Only the standalone script-tag bundle needs report-designer.worker.js, report-designer.help.js, report-designer.pdf.js and report-designer.pdf-worker.js next to it.

Package entry points#

The user guide as standalone HTML#

Template authors read the user guide inside the designer (Help, or F1). If you want it in your own help system or intranet as well, the package contains it as static HTML: node_modules/@rd/designer/dist/user-guide/index.html. It uses relative links only, works from file://, and can be served at any path. The render service also serves it at /help/.

This developer portal is not part of the npm package. It is served by the render service at /.

Loading the designer from your render service#

Script-tag hosts don't have to copy anything: the render service serves the standalone bundle, its sibling files and its fonts at /sdk/<version>/ (immutable) and /sdk/latest/, with CORS open and SRI values in /sdk/<version>/manifest.json. See Load it from your render service.

Bundle size#

Most of the size is the PDF engine, which the in-browser preview needs. Load the designer on its own route (import('@rd/designer') inside a lazily loaded route or component), so the rest of your app doesn't pay for it. UI translations for languages other than English, and the built-in help (about 3 MB gzip), are separate lazy chunks that load only when used.

Browser support#

Current versions of Chrome, Edge, Firefox and Safari. Required platform features: custom elements and Shadow DOM, ES2022, module Web Workers (with a main-thread fallback) and the FontFace API. The designer needs no license and does no license check in the browser: its previews always carry a light "PREVIEW" watermark, and the final PDFs come from the render service (License).

Installing the render service#

See Deployment and operations. In short:

npm install --omit=dev ./rd-fonts-1.0.0.tgz ./rd-fonts-cjk-1.0.0.tgz ./rd-core-1.0.0.tgz ./rd-server-1.0.0.tgz
PORT=8080 node node_modules/@rd/server/dist/main.js

Fonts: font-base-url#

The designer needs font files at runtime for three things: drawing text on the canvas, listing fonts in the font picker, and rendering the PDF preview. They are two packages that are designed to share one served folder (their file names never clash):

node_modules/@rd/fonts/fonts/          required
  manifest.json            families, aliases (Arial → Arimo, …), CJK fallback chains (about 9 KB)
  Arimo-Regular.ttf  …     23 Latin/Greek/Cyrillic families, about 28 MB in total
  licenses/                SIL Open Font License texts (keep them with the fonts)
node_modules/@rd/fonts-cjk/fonts/      optional: Chinese, Japanese, Korean
  manifest-cjk.json        the 4 CJK families
  NotoSansSC-Regular.ttf … Noto Sans SC, TC, JP and KR, 5–10 MB per file, about 56 MB in total
  licenses/

The designer and the engine read manifest.json from font-base-url, then manifest-cjk.json from the same folder if it is there.

Rule: when a bundler includes the designer, its default URL (./fonts/ next to the script) points into your build output, where the fonts aren't. Copy both folders into one and set the attribute:

Leave out the @rd/fonts-cjk part if you didn't install it.

If the URL is wrong, the console shows [report-designer] could not load font manifest from …, the font list is empty, and the preview fails.

What is downloaded. Only manifest.json (about 9 KB) at startup. Each font face is fetched on first use (100–500 KB for Latin faces). The CJK faces are fetched only when displayed text contains such characters.

Caching. Font files never change within a release. Serve them with a long cache lifetime (Cache-Control: public, max-age=31536000, immutable) under a versioned path such as /rd-fonts/1.0.0/. Give manifest.json a short lifetime or the same versioned path.

CDN or another origin. Point font-base-url at a full URL (https://cdn.example.com/rd-fonts/1.0.0/). The files are fetched with fetch(), so the CDN must send CORS headers (Access-Control-Allow-Origin: https://your-app.example.com), and your CSP must allow the origin in connect-src.

Server fonts. The render service uses its own copy of the same fonts (@rd/fonts and @rd/fonts-cjk; the release executable's fonts/), plus any in RD_FONT_DIR. If you add corporate fonts on the server, add the same files to the designer's fonts folder with a manifest.json entry, or ask authors to upload them into templates.

The preview worker#

The PDF preview renders in a Web Worker so the page stays responsive.

• npm/bundler build: the worker is inlined into a lazily loaded chunk and started from a blob: URL. There is nothing to host.
• Standalone bundle: serve report-designer.worker.js next to report-designer.js.
• If the worker can't start (a missing file, or a CSP without blob: in worker-src), the preview silently falls back to the main thread. designer.renderInWorker tells you which path is active.

Content Security Policy#

A policy that works for the designer, with assets on your own origin:

default-src 'self';
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:;
font-src 'self' data: blob:;
connect-src 'self' blob: data:;
worker-src 'self' blob: data:;
frame-src blob:;

The plain-HTML sample in Plain HTML uses an inline module script. Under this policy, move that script to a .js file.