Introducing wolkenkit 2.0

tl;dr: wolkenkit is an open source CQRS and event sourcing framework for JavaScript and Node.js. The new version, wolkenkit 2.0, introduces an updated API and provides various improvements and fixes. The update finally introduces support for the two new JavaScript keywords async and await.

The past 12 months have been a highly exciting time for us. The wolkenkit CLI has been downloaded more than 2500 times. We have been to conferences and meetups in various countries and cities, including Basel, Belgrade, Cologne, Frankfurt, Freiburg, Karlsruhe, Munich, Stuttgart, and a few other places. Additionally we were guests in the episode 314 of the Working Draft podcast.

Besides a number of blog posts on CQRS, event sourcing, DDD, and wolkenkit have been published – not only in our blog, but also in cooperation with great companies such as Intuity, Heise developer, Auth0, and Maiborn-Wolff.

Introducing wolkenkit 2.0

Using async and await

With version 2.0, we want to further evolve wolkenkit. No matter how many effort you put into designing and developing, there are always things you only learn as time passes by.

With respect to this, the first aspect that this is true for is the rise of two new keywords in JavaScript, async and await. When we started developing wolkenkit in 2012, callbacks were state of the art. In 2018 this is not true any more, so we rewrote the entire API to make use of the new keywords, which helps to improve the readability of your code. E.g., when defining a command you now write

const commands = {
  async open (game, command) {
    // ...

instead of:

const commands = {
  open (game, command, mark) {
    // ...


This not only makes your code shorter and more streamlined, this also means you can't forget to call mark.asDone or mark.asRejected anymore, which was one of the most annoying mistakes when defining commands.

Improving the terminology

While updating the API we also realized that the terminology we chose was ambiguous, and could sometimes lead to confusion. The most prominent example for this was when, which was used in read models as well as in stateless and stateful flows – unfortunately, with a slightly different meaning in each case.

In read models, where it's about projecting domain events to lists, we are now using the much more accurate term projections. In flows, we use the term reactions. This is not only closer to the official terminology of CQRS, event sourcing and DDD, it also helps to better distinguish between which function does what.

Virtual machines and Internet Explorer compatibility

Additionally, there are now ready-made virtual machines available, for VirtualBox as well as for VMware. In case you need a Vagrantfile to quickly get up and running, we also have you covered. Most of the work on the virtual machines was done by @claudiobianco, whom we would like to thank for this great contribution!

Furthermode, the compatibility of wolkenkit SDK with Internet Explorer 11 was improved a lot: You do not need a polyfill any more, so using the SDK has become easier.

Starting with wolkenkit 2.0 we also ask developers whether they agree to share data on their use of the wolkenkit CLI with us, to help us improving wolkenkit even more. By default, sharing data is disabled, and even if you do share data, everything is entirely anonymized. See this blog post for details on why we do this, and what we do to protect your privacy.

As said, there are way more improvements and fixes, e.g. in the underlying eventstore. Thanks to @lorenzleutgeb for finding and suggesting fixes for a few bugs here! To get a complete overview of what's new and updated, have a look at the changelog.

Updating the release process

Also, internally a few things have changed, especially with respect to the release process. So far, creating a new release of wolkenkit needed to be done manually, and took at least half a day. It is pretty obvious that this should be done in a different way.

Thanks to the great help of @scherermichael we now have a fully automated release process, which makes it so much easier to create releases in the future. Thanks for that!

Updating to the new version

To update to wolkenkit 2.0, basically all you have to do is to install the new CLI using npm. The new CLI is fully backwards compatible and also supports the 1.0.0, 1.0.1, 1.1.0 and 1.2.0 runtimes, so you can easily upgrade to the new version without breaking anything. What has worked before, will continue to work:

$ npm install -g wolkenkit

To update an application to the new runtime version, you need to make a few adjustments to your code due to the changes we have made to the API. We have described in detail what you need to do in the updating an application section in the wolkenkit documentation.

Getting help

As always, if you need more details on how things work in wolkenkit, have a look at the wolkenkit documentation. We would like to thank @colorizedmind for his contributions to the documentation, especially for the updates to the installation guide for Windows, which is now so much better and clearer!

If you have any questions or need help, you are welcome to join the wolkenkit Slack team. Also, there are a number of questions on wolkenkit on StackOverflow, so maybe your question had already been answered before. In this context, we would like to give special thanks to @marcusstenbeck and @schmuto for their especially valuable feedback!

Getting started

If you are new to wolkenkit, and version 2.0 is your first release, you may be interested in the brochure on CQRS, event sourcing, DDD and wolkenkit, which you can download for free as PDF (alternatively you may order professionally printed copies).

There is also a variety of articles available. We have also collected a list of blog posts. Finally, there are a number of sample applications you may be interested in. Thanks to @revrng for submitting a geocaching sample application!


Finally, there is only one thing left to say: We are very looking forward to the next year of wolkenkit, and as always – if you want so help us improve wolkenkit even further, feel free to contact us via email at!

Thanks, and have a nice time with wolkenkit!

Yours, Sophie and the team of the native web

Twitter Facebook LinkedIn

Sophie van Sky

Cloud adventurer

We believe that openness is the foundation to build sustainable software. This very same principle we apply to technology. Hence we favor open standards over proprietary vendor-specific engineering.