Carbone: Node.js report generator from JSON to PDF and Office formats via XML templates

Carbone fills Office XML templates with JSON data, working server-side only

Carbone is a report generator for Node.js that produces PDF, DOCX, XLSX, ODT, PPTX, ODS and other document formats from a template and a JSON data object. Any XML-based document created in LibreOffice, Google Docs, Microsoft Office or a compatible editor works as the template. Inside that template, mustache-like markers in the form `{d.companyName}` stand as placeholders that Carbone replaces with values from the JSON data at render time.

That design means formatting, pagination, headers, footers and table structures are authored in the editor you already use, rather than assembled in code. Carbone analyzes the XML structure of the template and injects the data. The generated document can be exported in its original format or converted to PDF when LibreOffice is installed on the system.

One constraint is stated plainly in the README: Carbone is working only on the server-side. There is no browser runtime and no client-side rendering path. A Node.js process is required on the host. The minimum Node.js version is listed as 14.x+ in the README. The project runs on macOS, Linux (servers and desktop), and Windows, according to the minimum requirements section.

JSON objects and arrays are the supported data input formats. A project that already exposes JSON API responses can pipe that data directly into `carbone.render` without a transformation layer.

npm install carbone and a first carbone.render call against an ODT template

The package is published on npm as `carbone`. Adding it to a project requires a single line.

npm install carbone

The open-source edition is at version 3.8.2, from `package.json` at the repository root. That file states the engine requirement as `>= 12.14.0`, while the README lists the minimum as Node.js 14.x+.

The basic usage pattern from the README renders an ODT template with a two-field data object and writes the result to disk.

const fs = require('fs');
const carbone = require('carbone');

var data = {
  firstname : 'John',
  lastname : 'Doe'
};

carbone.render('./node_modules/carbone/examples/simple.odt', data, function(err, result){
  if (err) {
    return console.log(err);
  }
  fs.writeFileSync('result.odt', result);
});

`carbone.render` takes the template path, the data object, and a callback. The callback receives an error and a result buffer, which the example writes to `result.odt` using `fs.writeFileSync`. Without LibreOffice present, the output format matches the template format: an ODT template without LibreOffice produces ODT output and cannot produce PDF. The repository ships example templates under `examples/`, including `simple.odt`, `flat_table.ods`, and `movies.docx`.

LibreOffice starts in headless server-mode with managed workers and a three-attempt retry queue

PDF generation goes through LibreOffice. Carbone does not implement its own PDF renderer; it manages a LibreOffice process pool on behalf of the application. LibreOffice runs in headless server-mode with no user interface loaded. Worker count is configurable, and a worker that crashes or stops responding is replaced automatically. Conversions that fail enter a retry queue that attempts the job three times before giving up.

That architecture offloads PDF quality and format fidelity to LibreOffice, which handles the full document layout. It also introduces a native dependency that must be installed separately on each server, monitored as a background process, and upgraded on a schedule that is independent of the Node.js package version. A Carbone deployment that generates PDF is not a pure Node.js deployment, and operations teams that manage it need to plan for LibreOffice health alongside the application.

For formats that do not require format conversion, Carbone can produce DOCX, XLSX, PPTX, ODT, ODS, ODP and HTML without LibreOffice, provided the template format matches the desired output format. A DOCX template without LibreOffice on the server produces DOCX and nothing else.

The Ubuntu PPA LibreOffice lacks Python and breaks Carbone's document converter

Installing LibreOffice on an Ubuntu server for use with Carbone has a documented failure mode. The `libreoffice/ppa` PPA omits Python, which Carbone's converter requires. A server that uses the PPA package will have a broken converter, and the failure may not be obvious from the Node.js error output.

For Ubuntu server and Ubuntu desktop, the README recommends removing any existing LibreOffice installation first, then downloading the package directly from the official LibreOffice website.

# remove all old version of LibreOffice
sudo apt remove --purge libreoffice*
sudo apt autoremove --purge

# Download LibreOffice debian package. Select the right one (64-bit or 32-bit) for your OS.
# Get the latest from http://download.documentfoundation.org/libreoffice/stable

On macOS, the README recommends installing the stable version from https://www.libreoffice.org/. These are the only two platforms with specific LibreOffice installation guidance in the README. Windows is listed in the minimum requirements section as a supported platform, but the README does not document LibreOffice setup steps for it.

The npm edition is one major version behind, and Chrome and OnlyOffice converters are v5 only

The open-source npm edition of Carbone is always one major version behind the Docker and Cloud editions. At the time of the last repository push, the npm edition was at version 3.8.2, while the Docker edition (`carbone/carbone-ee`) is at v5+. The README states the project will update the open-source edition to v4 as soon as possible.

One practical consequence: Carbone v5 adds support for Chrome and OnlyOffice as document converters alongside LibreOffice. That capability is not available in the npm edition at v3.8.2, where LibreOffice is the only converter.

The Docker edition can be pulled without a licence to access community features, using the same REST API as the Cloud edition at carbone.io. A licence is required only for advanced features.

docker pull carbone/carbone-ee:latest

Projects that need v5 capabilities must use the Docker or Cloud edition rather than embedding the npm package directly. The README does not document a timeline for when the npm edition will reach v5.

Template-based generation assumes an Office document exists; programmatic generation does not

Carbone's model requires a template file: a real Office document that someone authors in an editor, with `{d.companyName}`-style markers placed where data belongs. That design works well when the document layout is complex, when a business stakeholder needs to visually approve the template, or when formatting must match an exact standard. Changing the layout means editing the template file in an editor and re-deploying that file as a versioned asset.

An alternative approach builds documents programmatically: code describes each element's position, font, size and content at runtime, with no template file to maintain. That removes the LibreOffice dependency on the server and eliminates the separately managed template asset. It also moves all layout decisions into code, which means the people authoring the output format must be comfortable reading and editing code rather than using an Office editor.

Carbone fits document-heavy workflows where templates are produced by designers or business users who work in Office tools. Programmatic generation is better suited to documents whose structure is fully determined by code, or when the server environment cannot run LibreOffice. Neither is universally superior.

Custom licence in LICENSE.md, pinned exact versions, and last push on 2026-04-07

The licence is described in `LICENSE.md` at the repository root. `package.json` uses "SEE LICENSE IN LICENSE.md" rather than a standard SPDX identifier, and GitHub classifies the licence as "Other". Reading `LICENSE.md` directly is the only way to confirm the terms before using the package in a commercial or redistribution context.

Runtime dependencies in `package.json` are `dayjs` at version 1.11.20, `debug` at 4.4.3, `which` at 6.0.1, `yauzl` at 2.10.0, and `yazl` at 2.5.1. All five are pinned to exact versions with a leading equals sign in the version string, rather than a semver range. Updating any of them requires an explicit change in `package.json`. `mocha` at version 9.2.2 is the only listed dev dependency.

The last push to the repository was on 2026-04-07. The repository is not archived. Since the open-source npm edition trails the Docker and Cloud editions by at least one major version, the npm package may continue to lag behind the Docker edition regardless of future push activity, because the two editions develop separately. The News section of the README is dated 2026/04, consistent with the last push date.

Editorial conclusion

Carbone suits Node.js projects that generate documents from Office templates, where layout is authored in an editor and PDF output goes through a LibreOffice server. Skip it when the deployment environment cannot run LibreOffice, when Docker is unavailable and v5 features are needed, or when a non-standard licence creates legal obstacles. Before adopting, read `LICENSE.md` to confirm the terms match your use case, verify that your Ubuntu LibreOffice install came from the official website rather than the PPA, and check whether the version gap between the npm edition and the Docker edition affects features you plan to use.

Frequently asked questions

Official sources

1. carboneio/carbone on GitHub
2. Issues
3. Project website
4. README