Marble.js 🔥— when Node.js meets RxJS

Cover photo from: Getty Image/iStockphoto

The day has come. I’m thrilled to announce the official release of Marble.js: A functional reactive Node.js framework, built for RxJS and TypeScript hipsters. Let’s take a peek at what’s inside the candy store.

Lean startup

When the Angular team announced that version 2.0 would be deeply integrated with RxJS, not everyone was sure what that actually meant for the JS community. At this moment, we can easily put forward the argument, that the reactive paradigm in JavaScript is not just a trend… in the frontend world, of course.

Looked at from the other side, when Kamil Mysliwiec released NestJS in 2017, I was really excited. A TRUE Node.js framework, heavily inspired by Angular architecture, based on TypeScript language with solid patterns and decisions behind it. For me, it was a game-changer — the thing that I was really missing in the ecosystem.

As a functional programming fanboy and RxJS hipster, I often looked at the usage of the reactive paradigm on the server side of JavaScript, but there wasn’t much movement. Express, Koa, Hapi, Fastify, Restify, Sails and the new player NestJS… You can choose whatever you want and I’ve probably listed only half of them. We can be reactive if we truly want, we can use RxJS with Express, but it will still be affected by the usage. Marble.js was born with a clear vision — a reactive paradigm as a first class citizen, with functional sugar on top of the Node.js platform.

“OK my lord, please take a minute and tell us more about this ‘reactive’ thing…”

The general overview shows that even the Internet can’t find a proper explanation for what the heck it is. But let’s trying to put it in a very simplified form:

Reactive programming is programming with asynchronous data streams.

Reactive programming raises the level of abstraction of your code so you can focus on the interdependence of events that define the business logic, rather than having to constantly fiddle with a large amount of implementation details. [..]
~ Andre Staltz

Having this concept in mind, if we think about how a typical HTTP API works we can quickly transfer that thinking to a reactive style where we deal with streams of asynchronous events (aka HTTP requests). OK, I said — it looks cool on the paper, let’s do some code! The beginning of May was a crazy time. Everything started from the small proof of concept. After just one more week, I showed it to my friends — Patryk Domałeczny and Sebastian Musiał. They bought the concept very quickly. After yet another week we had a working MVP available on npm.

Everyone knows that the process of choosing a name is not as easy as you may think — especially when it comes to finding the proper name for your own baby. The name, Marble.js comes from a popular way of visually expressing the time-based behavior of event streams, aka marble diagrams:

☝️ example marble diagram |

Once we had the defined name, with big thanks to Patryk, we quickly designed a logo, a little bit inspired by the original ReactiveX branding. Having prepared the MVP, we pushed the big red button and launched the first test rocket. 🚀


The core concept assumes that almost everything is a stream. Knowing that RxJS isn’t so easy, we wanted to achieve as simplest an API as possible. If you’ve ever worked with libraries like Redux Observable on React or @ngrx/effects on Angular, you will feel at home.

The core is based on the Effect, the main building block of the whole framework, which is just a function that returns a stream of HTTP requests. Using its generic interface we can create more specialized blocks like endpoints, middlewares or error handlers. For those people who came from a functional programming background, you can compare it to a so-called “side-effect”, which in general is almost anything that interacts with the outside world (filesystems, networks, logging, databases, etc.).

☝️ Everything is a stream

As we know, every API requires composable routing. Because Marble.js is not based on an HTTP middleware engine, it was an area we focused on. We started from a totally different concept, from the very first RC, we introduced a totally rebuilt routing resolving mechanism under the hood. I would like give big thanks to my friend Krzysztof Miemiec, who helped us with this enhancement. Without his help, we wouldn’t have so huge boost in overall performance.

☝️ Example controller


From the very beginning, we wanted Marble.js to be based on solid documentation. To start quickly, we used a battle-tested and popular solution provided via the GitBook platform, which made it easy for us to write and maintain high-quality documentation.

Besides the most common parts of writing reactive RESTful APIs, like endpoints, middlewares and routing architecture, you can find here a detailed API reference for publicly available methods that you can find across the framework, and last but not least, the changelog that we have tried to align with recent updates on the GitHub repository.

We are looking for your support in improving the available documentation. If you think that it is lacking in some areas — just ping us on Twitter or post a GitHub issue!


From the beginning, the project received an incredibly positive response from the JS community. In the first week of its publication on GitHub, Marble.js earned more than 700 stars (and for a few days, it was the most popular TypeScript repository) and its fair share of exposure on social media, getting attention from, among others, Ben Lesh (the RxJS project lead) who gave us a big shot support from the beginning.

With interest in the reactive concept on the server side, we’ve got a surprisingly good response with a bunch of proposed improvements and cool ideas. What’s important to mention, thanks to Lucio Rubens, we’ve got the first big contribution with a very useful schema validation middleware based on the Joi library. 👏

The show must go on!

As Freddie Mercury sang, the show must go on and we definitely don’t want to rest on our laurels. We’ve just reached 1.0, which means that the framework is production ready. At this point, we have a well-defined roadmap for future releases which aims to complement the infrastructure with tooling and new middlewares. And for the curious, yes, WebSockets will land in Marble.js as well.

We’d love to see you build some great stuff with it and hope that the project will contribute to the popularization of the reactive paradigm on the server side. The seed is sown. Feel free to check out the docs, and for the latest updates follow us on Twitter.

We strongly believe that Open Source is all about the people. Dear supporters and contributors, thank you! Be prepared for the next Big Bang! 🔥