⚡️ Fast, Simple and Powerful report generator in any format PDF, DOCX, XLSX, ODT, PPTX, ODS, XML, CSV using templates and your JSON data as input !
News
15th of February 2023: Carbone just launched on Product Hunt! Feel free to support us. It will help us improve the engine!
Please consider using the Cloud or On-Premise Enterprise Edition if you need professional support.
The Community Edition is one major version behind the Enterprise Edition. Feel free to contact us on the chat if you need further information.
Table of content
README language: 🇨🇳 简体中文, 🇺🇸 English
Features
- 🍏 Extremely simple : Create templates with LibreOffice™, Google Docs, Microsoft Office™, TinyMCE, CKEditor, ...
- 🎨 Unlimited design : The limit is your document editor: pagination, headers, footers, tables...
- 📝 Convert documents : thanks to the integrated document converter
- 📐 Unique template engine : Insert JSON-like markers
{d.companyName}
directly in your document - ⭐️ Flexible : Use any XML documents as a template: docx, odt, ods, xlsx, html, pptx, odp, custom xml files...
- 🚀 Future-proof : A powerful XML-agnostic algorithm understands what to do without knowing XML document specifications
- 🌈 Multilingual : One template, multiple languages. Update translation files automatically
- 💎 Format data : Use built-in date and number formatters or create your own in Javascript
- 🏎 Fast : Manage multiple LibreOffice threads for document conversion, optimized code generation for each report
How it works?
Carbone is a mustache-like template engine {d.companyName}
.
Template language documentation : https://carbone.io/documentation.html
- The template can be any XML-document coming from LibreOffice™ or Microsoft Office™ (ods, docx, odt, xslx...)
- The injected data must be a JSON object or array, coming directly from your existing APIs for example
Carbone analyzes your template and inject data in the document. The generated document can be exported as is, or converted to another format (PDF, ...) using LibreOffice if it is installed on the system.
Carbone is working only on the server-side.
Minimum Requirements
- NodeJS 12.x+
- Runs on OSX, Linux (servers and desktop), and Windows
Optional
- LibreOffice server if you want to use the document converter and generate PDF. Without LibreOffice, you can still generate docx, xlsx, pptx, odt, ods, odp, html as long as your template is in the same format.
Getting started
Basic sample
1 - Install it
npm install carbone
2 - Copy-paste this code in a new JS file, and execute it with node
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);
});
PDF generation, document conversion
Carbone uses efficiently LibreOffice to convert documents. Among all tested solutions, it is the most reliable and stable one in production for now.
Carbone does a lot of thing for you behind the scene:
- starts LibreOffice in "server-mode": headless, no User Interface loaded
- manages multiple LibreOffice workers to maximize performance (configurable number of workers)
- automatically restarts LibreOffice worker if it crashes or does not respond
- job queue, re-try conversion three times if something bad happen
1 - install LibreOffice
on OSX
on Ubuntu Server & Ubuntu desktop
Be careful, LibreOffice which is provided by the PPA libreoffice/ppa does not bundled python (mandatory for Carbone). The best solution is to download the LibreOffice Package from the official website and install it manually:
sudo apt remove --purge libreoffice*
sudo apt autoremove --purge
wget https://downloadarchive.documentfoundation.org/libreoffice/old/7.5.1.1/deb/x86_64/LibreOffice_7.5.1.1_Linux_x86-64_deb.tar.gz
sudo apt install libxinerama1 libfontconfig1 libdbus-glib-1-2 libcairo2 libcups2 libglu1-mesa libsm6
tar -zxvf LibreOffice_7.5.1.1_Linux_x86-64_deb.tar.gz
cd LibreOffice_7.5.1.1_Linux_x86-64_deb/DEBS
sudo dpkg -i *.deb
sudo apt install ttf-mscorefonts-installer
sudo apt install fonts-wqy-zenhei
2 - generate PDF
And now, you can use the converter, by passing options to render method.
Don't panic, only the first conversion is slow because LibreOffice must starts
Once started, LibreOffice stays on to make new conversions faster
var data = {
firstname : 'John',
lastname : 'Doe'
};
var options = {
convertTo : 'pdf'
};
carbone.render('./node_modules/carbone/examples/simple.odt', data, options, function(err, result){
if (err) return console.log(err);
fs.writeFileSync('result.pdf', result);
process.exit();
});
More examples
Nested repetition in a docx document and spreadsheet
var data = [
{
movieName : 'Matrix',
actors : [{
firstname : 'Keanu',
lastname : 'Reeves'
},{
firstname : 'Laurence',
lastname : 'Fishburne'
},{
firstname : 'Carrie-Anne',
lastname : 'Moss'
}]
},
{
movieName : 'Back To The Future',
actors : [{
firstname : 'Michael',
lastname : 'J. Fox'
},{
firstname : 'Christopher',
lastname : 'Lloyd'
}]
}
];
carbone.render('./node_modules/carbone/examples/movies.docx', data, function(err, result){
if (err) return console.log(err);
fs.writeFileSync('movies_result.docx', result);
});
carbone.render('./node_modules/carbone/examples/flat_table.ods', data, function(err, result){
if (err) return console.log(err);
fs.writeFileSync('flat_table_result.ods', result);
});
API Reference
To check out the api reference and the documentation, visit carbone.io.
Command line tools
To checkout out the Carbone CLI documentation, visit carbone.io
Issues
If you're facing any issues with this Community Edition, search a similar issue to ensure it doesn't already exist on Github. Otherwhise, create an issue to help us.
Roadmap
The roadmap is pinned on the github issues list.
Performance
⚡️ Secret news of 14th Februrary 2023: we are building our own PDF converter, x200 faster than LibreOffice! Stay tuned.
Report generation speed (without network latency), using a basic one-page DOCX template:
- ~
10 ms / report
without document conversion (analyzing, injection, rendering) - ~
50 ms / report
with a PDF conversion (100 loops, 3 LibreOffice workers, without cold-start)
On a MacBook Pro Mid-2015, 2,2 Ghz i7, 16Go.
Licenses and editions
There are two editions of Carbone:
- Carbone Community Edition is freely available under the CCL Agreement. Roughly speaking, as long as you are not offering Carbone Community Edition Software as a hosted
Document-Generator-as-a-Service like Carbone Cloud, you can use and modify all Community features for free.
- Carbone Enterprise Edition (hosted and on-premise) includes additional features. See comparison table
The Community Edition is one major version behind the Enterprise Edition. This rule may change in the future.
Philosophy
Our ultimate goal
2% percent of our hosted solution revenues goes to charity
Contributors
Thanks to all Carbone contributors (random order)
- Florian Bezagu
- Matthieu Robin
- Arnaud Lelièvre
- Maxime Vincent
- Enzo Ghemard
- Jordan Nourry
- Etienne Rouillard
- Guillaume Chevaux
- Fabien Bigant
- Maxime Magne
- Vincent Bertin
- Léo Labruyère
- Aurélien Kermabon
- Steeve Payraudeau