New – Carbone v5

Page updated on December 1st, 2025.

How to use Carbone v5

• On-premise: Download links are available in the Changelog.
• Carbone Cloud Studio: https://studio.carbone.io/ v5 is used by default
• Carbone Cloud API: set the HTTP header carbone-version: 5. By default, the API uses v4.

Template Migration Guide

As always, the Carbone language is backward compatible when upgrading from previous versions. However:

1. Carbone v5 detects more syntax errors than Carbone v4. The most common issue is a missing i+1 tag, which Carbone v4 may have accepted in some cases. If you encounter migration issues, please contact us. We're here to help!

2. The main differences usually come from the converter version (LibreOffice).

   • If you use Carbone On-Premise, you can continue using an older version of LibreOffice with Carbone v5.
   • The Cloud Edition (API v5) uses the latest LibreOffice version (25.2), while Carbone Cloud v4 uses LibreOffice 7.5.
   • As a result, document conversion results may differ when switching from v4 to v5 (especially for DOCX to PDF). In general, the output is improved, but we recommend carefully reviewing your documents after migrating.

API Migration Guide

All APIs are backward compatible. They now support both the versionId and the new constant templateId (see below).

Studio - Design Assistant

Carbone v5 comes with a built-in designer assistant studio.

The new studio is composed of two parts (two pages):

• Designer Assistant: This is the main part of the studio where you can test, debug, and build your templates. Now, this part can be embedded into your application (as a Web Component).
• Template Manager: This part will display the list of templates, similar to a file explorer like Google Docs or Dropbox. This part is hidden during the beta phase.

Here are all the new features of the Designer Assistant:

Studio - Embedded

Embed Carbone Studio directly in your application!

From the software editor's perspective:

• Make all reports in your app customizable.
• Increase revenue potential by upselling access to this feature or offering personalized reports.

From the user's perspective:

• Enjoy a seamless experience by editing reports directly within the application.
• Automatically open the studio with user data as a sample.
• Add documentation to explain your data (coming soon).

From the developer's perspective:

• The studio is a customizable, lightweight HTML5 web component compatible with all front-end frameworks like Vue.js, React.js, Angular, and Riot.
• The studio requires only four endpoints to function.

1. Load the web component file

• Start Carbone On-Premise with the -s option to start the studio.
• Then, download the JS from there with this URL: http://localhost:4000/carbone-studio.js (More options with CDN will come soon)
• Include the JS file in your app:

  <script src="/carbone-studio.js"></script>
  <style>
    carbone-studio {
      height:100%;
      width:100%;
    }
  </style>

2. Start the studio

// Instantiate the Web component
const studio = document.createElement('carbone-studio');
// Or insert `<carbone-studio></carbone-studio>` directly in the DOM.
// Add the studio component to the DOM
document.body.appendChild(studio);             
// Configure the studio
studio.setConfig({
  origin : 'https://api.carbone.io/', // Defaults to `window.location.origin`
  token  : '',                        // Provide a JWT Token if authentication is enabled on your On-Premise instance
});


const templateFile = {
  // The studio will automatically call `URL_ORIGIN/template/:templateId` to download the template
  templateId : '424242424242424242424242424',
  // Extension is used for the user interface and may change in the future
  extension  : 'docx' 
};
// Pre-initialize the studio with data, language, etc.
const options = {
  data           : {},
  complement     : {},
  enum           : {},
  translations   : {},
  lang           : 'fr-fr',         // Defaults to browser language
  timezone       : 'Europe/Paris',  // Defaults to browser timezone
  currencySource : 'EUR',           // Defaults to browser currency
  currencyTarget : null
};
// Open the template in the studio
studio.openTemplate(templateFile, options);

3. Listen to events

  studio.addEventListener('connected');
  studio.addEventListener('disconnected');

  // Listen for updated options
  studio.addEventListener('options:updated', handler);
  // Event object:
  // {
  //   detail: {
  //     data         : <ObjectOrArray>
  //     complement   : <ObjectOrArray>
  //     enum         : <Object>
  //     translations : <Object>
  //   }
  // }

  // Listen for the `template:saved` event to get the new template Id
  studio.addEventListener('template:saved', handler);
  // Event object:
  // {
  //   detail: {
  //     templateId: 'af42af42af42af42af42af42af42af42af42af42af42af42'
  //     type      : 'docx'
  //   }
  // }

  // The `template:updated` event is still emitted, but it contains the template as a Base64 string (no template ID)
  studio.addEventListener('template:updated', handler);
  // Event object:
  // {
  //   detail: {
  //     dataURI : '',   // template in base64
  //     type    : 'docx'
  //   }
  // }

4. Override fetch request

  const studio = document.createElement('carbone-studio');
  window.addEventListener('DOMContentLoaded', function() {
    document.body.appendChild(studio);
    studio.setConfig({
      fetchOverride : fetchHandler // Override fetch behaviour in the Studio 
    });
    function fetchHandler(url, options) {
      console.log('Override fetch called:', url, options);
      const newOptions = {
        ...options,
        headers: {
          ...options.headers,
          'X-From-Studio': 'true'
        }
      };
      if (url.startsWith('/template/')) {}
      if (url.startsWith('/templates/')) {}
      if (url.startsWith('/render/')) {}
      return fetch(url, newOptions);
    }
  });

Document converters

Carbone merges data with templates, but document conversion (for example, DOCX to PDF) has traditionally been handled by a single external tool: LibreOffice.

Although we financially support The Document Foundation every year, we have in-depth knowledge of LibreOffice's technical limitations. That’s why we wanted to remove this constraint and offer more flexibility.

Now, you can choose from four different document converters, all managed directly by Carbone:

Converter	Performance	Precision	Document Features	Availability
LibreOffice (default)	+	Best for ODT/ODS/ODP/ODG to PDF	++++	Yes
OnlyOffice	++	Best for DOCX/XLSX/PPTX to PDF	++	Yes
Chrome	++	Best for HTML to PDF	+	Yes
Carbone Ice	+++++	Best for simple DOCX to PDF	-	Q4 2026

Carbone Ice is our own converter, intended for specific use cases where extremely high performance is required.
We may stop developing this solution if OnlyOffice or LibreOffice reaches similar performance 😛.

OnlyOffice Limitations:

• Table of Contents in DOCX files are not updated when generating documents.
• SVG support is very limited.
• Hidden characters are not supported.
• Repeated headers on page breaks are not supported.
• High memory usage (RAM).
• Slower performance with small documents (< 50 pages)
• No custom PDF export options (such as PDF/UA, compression quality, forms, etc.).

Converter selection

• With the API:

  {
    // L : LibreOffice
    // O : OnlyOffice
    // C : Chrome
    "converter" : "L",
    "convertTo" : "pdf",
    "data"      : {}   
  }

• In the studio:

Optimizations

A core principle in our development is ensuring that each new version is faster than the last. Carbone v5 is a major milestone, enabling document generation up to 10 times faster than Carbone v4.

Document Generation

Opening templates and saving generated documents can account for up to 35% of Carbone’s internal resource consumption, not including document conversion time. We achieved a 4× improvement in template opening speed and a 2× improvement in saving the generated document. Overall, this results in a 2× performance gain on a 15MB PPTX template (without PDF conversion) when comparing Carbone v4 and v5:

Multiple Converters, More Solutions for Huge Documents

Carbone v5 supports multiple document converters (see the previous section). OnlyOffice can be used as a replacement for LibreOffice. Here are our benchmarks for converting a large, complex 200-page DOCX file to PDF:

OnlyOffice may be slightly slower for small documents (mainly due to a higher cold start time compared to LibreOffice).

Carbone v5.0.3 also introduces a new formatter, :appendTemplate, which enables the possibility of generating documents with up to 20,000 pages in multi-threaded mode.

Fast Round Robin Conversion Queue

Carbone distributes conversion jobs across multiple threads using an extremely efficient technical stack.

We provide pre-built binaries on our own CDN (bin.carbone.io), offering optimized and compact versions of all these tools: LibreOffice, OnlyOffice, and Chrome, for multiple architectures (ARM, x64).

Carbone is extremely fast compared to other converters like Gotenberg, Collabora, JODConverter, or Puppeteer:

Feature Optimizations

In processing drop/keep tags: for templates containing many drop/keep tags (>10,000), processing can be up to 1000× faster.

When isDebugActive is true (for debugging in the studio), concatenating Carbone tags in the JSON result can also be up to 1000× faster for templates containing more than 10,000 Carbone tags.

Template Engine

All prerelease features delivered in v4 with optional flags {o.preReleaseFeatureIn=4022011} are now activated by default for all templates.

This new v5 engine is more stable and handles more complex use cases compared to v4, while maintaining backward compatibility with v4.

Here are the major improvements:

• Supports a wider range of use cases for conditional blocks and loops. It handles more scenarios and significantly reduces the likelihood of creating an invalid file ("Could not open document" error). The engine now accepts syntaxes that may not be logical for a computer but are understandable for a human, especially in documents. For example, writing tags in a document can sometimes generate an algorithm like this:

  IF
    START LOOP
      END IF
    END LOOP
    // END IF should be here for a computer. Carbone fixes this automatically

  This example below, which combines filters, aggregators, and a conditional block on the same array, was not supported without this new algorithm: Additionally, it is no longer necessary to repeat the full tag at the end of a conditional block; {d:showEnd} or {d:hideEnd} is sufficient.

  {d.arr[sort>1].id:aggCount:ifGT(0):showBegin}
    {d.arr[i].id}
    {d.arr[i+1].id}
  {d:showEnd}

• 😎 Improved syntax error detection and clearer messages when debug mode is activated (see screenshot of the studio above).

• 🥳 Enhanced support for XLSX files (e.g., no suppression of empty cells).

• Added support for bindColor in PPTX templates (for text, background color, and shapes).

• New :transform(axis, unit) formatter to move an image or shape in ODT/ODP/PPTX on the X or Y axis:

  • axis can be x or y to move the item horizontally or vertically from its current position. Positive numbers move the item to the right or bottom.
  • unit can be cm, mm, inch, or pt.

• Whitespace is now accepted in attribute names when using single quotes: {d.'new param'.'second level yes'[1].'sub obj'}. Known limitation: This is not accepted inside formatters, array filters, and aliases.

• Fix: Conditional blocks (show, hide) and smart conditional blocks (drop, keep) were not executed when combined with an array filter. In this example {d.arr[i, filter=3].id:ifEM:hideBegin} AAAA {d.arr[i, filter=3].id:hideEnd}, AAAA was printed if no rows matched the condition filter=3.

• ⚡️ Transform your JSON without limits using :set(). This formatter, introduced in v4.5.2, was previously limited. It can now be used to convert a flat JSON into a new hierarchical JSON with unlimited array depth, or vice versa (more details to come).

CLI + Env Variables

The CLI has been completely rewritten for greater clarity and ease of use when starting and deploying.

• Added new interactive tools to generate key pairs, tokens, and verify tokens.
• The Carbone CLI can now be used directly without needing to enter the Docker container. By default, it still starts the web server as before.
• A new CARBONE_AUTHENTICATION_PUBLIC_KEY environment variable allows passing the public key (in stringified PEM format) when authentication is enabled.
• Proper support for SNAKE_CASE_UPPER_CASE has been added for all environment variables. The previous format used an inconsistent partial snake_case.
  • For backward compatibility, both formats are accepted: CARBONE_EE_AUTHENTICATIONPUBLICKEY (old method) and CARBONE_AUTHENTICATION_PUBLIC_KEY (new method).
  • The new format takes precedence if both environment variables are provided.

API Template List & Constant Template ID

What problems does this solve?

• Enables you to maintain a constant template ID across versions.
• Gives you control over when a new template version is deployed to production.
• Allows you to list and manage all templates through the API.
• Supports storing optional metadata (such as name, comments, etc.) and sample data alongside templates.
• Unifies the user interface (Studio) for both On-Premise and Cloud deployments.

What's new?

All API endpoints now support two types of IDs when referencing a template:

• Version ID
  A SHA-256 hash of the template file, automatically generated by Carbone.
  This is the default behavior in Carbone v2, v3, and v4.
  The Version ID matches the filename of the template stored on disk (or S3 storage).
  Previously referred to as templateId in our documentation.

• Template ID
  A short and constant 64-bit ID, automatically generated by Carbone and optionally defined by the user.
  Multiple template versions can share the same Template ID.
  When calling endpoints with a Template ID (e.g., POST /render/{ID}), Carbone uses the latest deployed version (based on the deployedAt timestamp).
  If you wish to target a specific version, you can still call POST /render with the Version ID instead.

Summary:

To ensure backward compatibility, this new template storage method is only enabled if the versioning: true flag is set when creating a template via POST /template. In that case, the POST /template response is updated to reduce confusion:

Type	No Versioning	Versioning Enabled	Carbone Version
SHA-256 hash of the file	templateId	–	v5, v4, v3, v2
SHA-256 hash + random salt	–	versionId	v5 + versioning: true
64-bit constant ID	–	id	v5 + versioning: true

API Updates Summary

  # Updated endpoints:
  POST   /template                            # Create a new template or a new version of an existing template
  GET    /template/{templateId-or-versionId}  # Download the template file
  DELETE /template/{templateId-or-versionId}  # Delete a template
  POST   /render/{templateId-or-versionId}    # Generate reports using templateId or versionId

  # New endpoints:
  PATCH  /template/{templateId-or-versionId}  # Update metadata: name, comment, tags, expireAt, deployedAt
  GET    /templates                           # List all deployed templates and their versions
  GET    /templates/categories                # List all categories used in templates
  GET    /templates/tags                      # List all tags used in templates

Roadmap

	Sept-2025	Next
HTTP API v5 (same scope as v4)	Stable
Carbone template engine	Stable
LibreOffice converter	Stable
OnlyOffice converter	Stable
Chrome converter	Stable
Better XLSX Templates processor	Stable
Better HTML/XML Templates processor	Stable
SVG Templates processor	Stable
PDF Form templates processor	Stable
Nested Template (appendTemplate)	Stable
Open Metrics	Stable
Improved :html formatter (color, ...)	Stable
Studio - Designer assistant	Stable
Studio - Embedded	Stable
Studio Viewer HTML/XML	Stable
Template manager/versioning/constant ID (Studio + HTTP API)	Stable
Multi-tenancy + database backup S3		Q4 2025
Improved :html formatter (table support)		Q4 2025
MD to HTML converter		Q4 2025
keep/drop(column)		Q1 2026
AI Template generator		Q1 2026
AI Assistant		Q1 2026
PDF Comparison (Visual and Text Differences)		Q2 2026