Fast, Simple and Powerful report generator. Injects JSON and produces PDF, DOCX, XLSX, ODT, PPTX, ODS, ...!
Fast, Simple and Powerful report generator in any format PDF, DOCX, XLSX, ODT, PPTX, ODS [, ...]
... using your JSON data as input.
{d.companyName} directly in your documentCarbone is a mustache-like template engine {d.companyName}.
Template language documentation : https://carbone.io/designer-documentation.html
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.
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');
// Data to inject
var data = {
firstname : 'John',
lastname : 'Doe'
};
// Generate a report using the sample template provided by carbone module
// This LibreOffice template contains "Hello {d.firstname} {d.lastname} !"
// Of course, you can create your own templates!
carbone.render('./node_modules/carbone/examples/simple.odt', data, function(err, result){
if (err) {
return console.log(err);
}
// write the result
fs.writeFileSync('result.odt', result);
});
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:
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:
# 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
# or download the version currently "carbone-tested":
wget https://downloadarchive.documentfoundation.org/libreoffice/old/5.3.2.2/deb/x86_64/LibreOffice_5.3.2.2_Linux_x86-64_deb.tar.gz
# Install required dependencies on ubuntu server for LibreOffice 5.0+
sudo apt install libxinerama1 libfontconfig1 libdbus-glib-1-2 libcairo2 libcups2 libglu1-mesa libsm6
# Uncompress package
tar -zxvf LibreOffice_5.3.2.2_Linux_x86-64_deb.tar.gz
cd LibreOffice_5.3.2.2_Linux_x86-64_deb/DEBS
# Install LibreOffice
sudo dpkg -i *.deb
# If you want to use Microsoft fonts in reports, you must install the fonts
# Andale Mono, Arial Black, Arial, Comic Sans MS, Courier New, Georgia, Impact,
# Times New Roman, Trebuchet, Verdana,Webdings)
sudo apt install ttf-mscorefonts-installer
# If you want to use special characters, such as chinese ideograms, you must install a font that support them
# For example:
sudo apt install fonts-wqy-zenhei
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' //can be docx, txt, ...
};
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(); // to kill automatically LibreOffice workers
});
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);
});
<string>: path to the template relative to defaultTemplatePath, which is process.cwd() by default<object|array> : data to inject in the template<object> : options, details below<Function> : three parameters, err, result (Binary), reportName (String)options can one of these parameters:
{
convertTo : 'pdf', // String|Object, to convert the document (pdf, xlsx, docx, ods, csv, txt, ...)
lang : 'en-us', // String, output lang of the report
complement : {}, // Object|Array, extra data accessible in the template with {c.} instead of {d.}
variableStr : '{#def = d.id}', // String, predefined alias string, see designer's documentation
reportName : '{d.date}.odt', // String, dynamic file name, output in third argument of the callback
enums : { // Object, list of enumerations, use it in reports with `convEnum` formatters
'ORDER_STATUS' : ['open', 'close']
'SPEED' : {
10 : 'slow'
20 : 'fast'
}
},
translations : { // Object, dynamically overwrite all loaded translations for this rendering
'fr-fr' : {'one':'un' },
'es-es' : {'one':'uno'}
}
}
convertTo can be an object for CSV export
{
formatName : 'csv',
formatOptions : {
fieldSeparator : '+',
textDelimiter : '"',
characterSet : '76' // utf-8
}
}
characterSet can be one these options : https://wiki.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Filter_Options
Same as render function, except that it accepts pure XML string instead of a template path
Example:
var data = {
param : 'field_1'
};
carbone.renderXML('<xml>{d.param}</xml>', data, function (err, result) {
console.log(result); //output <xml>field_1</xml>
});
This function is not asynchronous (It may create the template or temp directory synchronously).
Set general carbone parameters.
options can contains {
tempPath : os.tmpdir(), // String, system temp directory by default
templatePath : process.cwd(), // String, default template path, and lang path
lang : 'fr-fr', // String, set default lang of carbone, can be overwrite by carbone.render options
translations : { // Object, in-memory loaded translations at startup. Can be overwritten here
'fr-fr' : {'one':'un' },
'es-es' : {'one':'uno'}
},
factories : 1, // Number of LibreOffice worker
startFactory : false // If true, start LibreOffice worker immediately
}
Example:
carbone.set({
lang : 'en-us'
});
Carbone comes with embedded formatters
You can add your own formatters, and overwrite default ones.
customFormatters must be an object containing one or many functions. Example: carbone.addFormatters({
// this formatter can be used in a template with {d.myBoolean:yesOrNo()}
yesOrNo : function (data) { // data = d.myBoolean
if (this.lang === 'fr-fr') {
return data === true ? 'oui' : 'non';
}
return data === true ? 'yes' : 'no';
}
});
The function signature must be like this:
function(data, firstParam, secondParam, ...) {
return '' // value printed in a rendered report
}
For convenience, install carbone globally
npm install carbone -g
With this command, Carbone parses all your templates, find translation markers like {t(movie)}, and updates JSON translation files accordingly.
It creates automatically a lang directory with all translation files, one per lang. It never loses already translated sentences.
Carbone loads translation files at startup if it finds a lang directory in the default template path.
carbone translate --help
# example:
carbone translate -l fr-fr -p path/to/template_default_path
If you want to find where a deprecated formatter is used among all your templates, carbone provides a search tool
carbone find needle
It searches among all reports in the current working directory and its subdirectories
Report generation speed, 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.
It could be even better when "code cache" will be activated. Coming soon...
There are two editions of Carbone:
We want to follow the model of Gitlab. The free version must be and must stay generous.
Our ultimate goal
We will give 3% percent of our hosted solution revenues to charity in three domains: technology, people and resources.
Stay tuned, best contributors could choose where a part of these 3% goes!
We already know that beneficiaries will be, at least :heart:
Help is welcome!
Thanks to all Ideolys's direct contributors (random order)
Thanks to all French citizens (Crédit Impôt Recherche, Jeune Entreprise Innovante, BPI)!
FAQs
Fast, Simple and Powerful report generator. Injects JSON and produces PDF, DOCX, XLSX, ODT, PPTX, ODS, ...!
The npm package carbone receives a total of 4,923 weekly downloads. As such, carbone popularity was classified as popular.
We found that carbone demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.
Product
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
Research
Security News
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.