Invoice compiler

October 05, 2014 • hack

Writing invoices to clients has been one of the more annoying tasks in our monthly routine. Our invoice compiler now automates a large portion of that.

We use Time-Tracker to log our billable hours. Previously, we would aggregate the numbers at the end of the month and manually calculate the subtotals/taxes before putting them into our Word template. This process is very error prone, so we had another person to double-check.

We developed the invoice compiler to improve that situation. It takes custom YAML files and outputs pdf. For devs like us, it feels natural to write YAML in our favorite text editor. It comes in very handy that we can easily duplicate and modify them. We can even put them in version control, so they are securely backed up.

Writing invoices in YAML

You can find an annotated sample in the repository. Also, check the generated pdf.

The invoice items are specified in a simple list. One of our favorite features is the support for simple calculations. Combined with comments this makes it very easy to trace the quantities if you have non-straightforward billing schemes.

    # Supports calulations (and comments)
    quantity: |
      30 + # Small
      28 + # Medium
      1 # Mega-large
    # Supports multiline titles
    title: |
    tax_rate: 19
    price: 0.6

Powered by HTML templates

First, we had a version that used LaTeX to render the documents. The original LaTeX classes were created by a friend of ours, Patrick Lühne. Once we wanted to change stuff it was very hard for us, because we are not that fluent in TeX.
So, we decided on a more familiar approach with HTML templates that can be styled with CSS. Enabling all the good stuff we’re used to. By the way: Did you know CSS supports units like cm and mm?

The invoice compiler uses wkhtmltopdf to turn the rendered html files into a pdf. It is a very nice tool for all sorts of automated document generation. Compared to PhantomJS it provides better performance because it is more lightweight and has better options to render headers/footers on each page. Another option is to create pdf files procedurally (draw this textbox at this location). However, HTML/CSS greatly reduces your layouting efforts.

└── scalableminds-de
    ├── footer.html
    ├── header.html
    ├── logo.svg
    ├── main.html
    └── style.css

You can use a customized template by putting a templates folder (as shown) next to your YAML file and specify the template’s name (ie. scalableminds-de) in the YAML file.

Installation & Usage

You can install the compiler with npm:

npm install -g invoice-compiler

Make sure to also install wkhtmltopdf on your system. And the default template uses the Open Sans font, which you need to install.

Use the CLI to render your invoices. It will output the pdf in the directory of the YAML file.

invoice sample.yml


As a software agency, we’re constantly thinking of how to improve our workflow – especially when it comes to recurring and annoying tasks. Building the invoice compiler was a quick project that improves our process a lot. wkhtmltopdf is an awesome tool, if you want to automate document creation and are thinking in angle brackets already.

invoice-compiler on npm

by Norman Rzepka

Related posts