jsreport Node.js Client

Common errors

• Error: connect ECONNREFUSED 127.0.0.1:5488

  cause The jsreport server is not running or is not accessible at the specified URL and port.
  fix Verify that your jsreport server is running and listening on `http://localhost:5488` (or the configured `serverUrl`). Check firewall rules or network connectivity. The `jsreport-cli` can be used to start a local server.

• Error: self signed certificate in certificate chain

  cause The jsreport client is attempting to connect to an HTTPS server with a self-signed or untrusted SSL certificate, and `strictSSL` is enabled.
  fix If in a development environment and the certificate is intentionally self-signed, initialize the client with `strictSSL: false`. For production, ensure the client's Node.js environment trusts the server's SSL certificate by adding the CA to the system's trusted certificates or specifying a custom `ca` option if supported by the client.

• TypeError: client.render is not a function

  cause The `client` object was not correctly instantiated, or the `jsreport-client` package itself was not imported correctly.
  fix Ensure you are importing and initializing the client factory function correctly: `import Client from 'jsreport-client'; const client = Client({ serverUrl: '...' });`. Double-check the package name in `package.json` to confirm it's `jsreport-client`.

Warnings

• breaking Version 1.0.0 introduced significant breaking changes aligned with jsreport v2. The `render` method no longer accepts a callback and instead returns a Promise. Direct access to Node.js HTTP response streams was also changed.
  Fix: Update all `client.render()` calls to use `await` or `.then()` for Promise-based handling. Review the jsreport v2 migration guide for other potential breaking changes in the server-side API.
• breaking In version 1.1.0, the underlying HTTP client was switched from the `request` package to `axios`. This change might affect applications that relied on specific `request` options, custom HTTP agents, or behavior unique to the `request` library.
  Fix: Review any custom HTTP client configurations passed to `jsreport-client` and adapt them to `axios` compatible options. Ensure network proxies or certificate handling configured for `request` are correctly translated for `axios`.
• gotcha Version 1.1.2 replicated the `strictSSL:false` option with `axios`. While convenient for development with self-signed certificates, relying on `strictSSL:false` in production can pose security risks by disabling SSL certificate validation.
  Fix: Avoid `strictSSL:false` in production environments. For self-signed certificates, properly configure your Node.js environment with the trusted CA certificate. Use environment variables to conditionally set `strictSSL` for development vs. production (e.g., `strictSSL: process.env.NODE_ENV === 'production'`).
• gotcha Version 1.2.0 made infinite body size the default for HTTP requests. While this prevents issues with large report data, it could potentially mask underlying problems with excessively large payloads or resource exhaustion if not managed properly by the jsreport server.
  Fix: Monitor memory usage on both the client and jsreport server when dealing with very large report payloads. Ensure the jsreport server itself is configured to handle large requests efficiently.
• gotcha This `jsreport-client` package (version 1.x) is designed for jsreport v2 servers. Newer jsreport server versions (v3 and above) are typically designed to work with the `@jsreport/nodejs-client` package, which has a different import path and potentially updated API. Using this older client with a newer server might lead to compatibility issues.
  Fix: For jsreport v3+ servers, consider migrating to `@jsreport/nodejs-client` (install via `npm i @jsreport/nodejs-client`). If sticking with `jsreport-client` (v1.x), ensure your jsreport server is running a compatible v2 version.

Install

• npm install jsreport-client npm
• yarn add jsreport-client yarn
• pnpm add jsreport-client pnpm

Imports

• Client
  wrong:

  const Client = require('jsreport-client');

  correct:

  import Client from 'jsreport-client';

  The package exports a factory function as its default export. TypeScript users typically import it as 'Client'. CommonJS users use require directly. For jsreport v3 and newer, the package name changed to @jsreport/nodejs-client, but this package (jsreport-client) is for older versions.
• jsreportClientInstance
  wrong:

  const client = new Client('http://localhost:5488');

  correct:

  const client = Client({ serverUrl: 'http://localhost:5488' });

  The imported 'Client' is a factory function, not a class constructor. It should be called directly to create an instance with an options object.

Quickstart

Demonstrates how to initialize the jsreport client and render a PDF report using a simple Handlebars template and data, saving the output to a file.

import Client from 'jsreport-client';
import fs from 'fs/promises';
import path from 'path';

async function generateReport() {
  // Initialize the jsreport client with the server URL (and optional credentials)
  const client = Client({
    serverUrl: process.env.JSREPORT_SERVER_URL ?? 'http://localhost:5488',
    username: process.env.JSREPORT_USERNAME,
    password: process.env.JSREPORT_PASSWORD,
    // Ensure strictSSL is false for self-signed certificates in development
    strictSSL: process.env.NODE_ENV === 'production' // Only enforce SSL for production
  });

  try {
    // Render a report using a raw template definition and some data
    console.log('Attempting to render report...');
    const response = await client.render({
      template: {
        content: '<h1>Hello {{:name}} from jsreport!</h1><p>Generated at {{new Date().toLocaleString()}}</p>',
        engine: 'handlebars',
        recipe: 'chrome-pdf' // Assuming chrome-pdf recipe is available on the server
      },
      data: {
        name: 'JSReport User'
      }
    });

    // Save the generated report content to a PDF file
    const outputPath = path.join(process.cwd(), 'hello-jsreport-report.pdf');
    await fs.writeFile(outputPath, await response.content());
    console.log(`Report successfully generated and saved to ${outputPath}`);
  } catch (e: any) {
    console.error('Error generating report:', e.message);
    if (e.statusCode) {
      console.error('Status Code:', e.statusCode);
      console.error('Response Body:', e.body);
    }
    process.exit(1);
  }
}

generateReport();