Every revolution begins with a Riot.js first

Gianluca Guarini
6 min readMay 30, 2019


Eugène Delacroix — Le 28 Juillet. La Liberté guidant le peuple


I started using Riot.js few years ago and it has changed my style of developing web applications.
I was tired to learn every day new concepts and convoluted ways to create always the same trivial components (accordions, overlays, custom input fields…).
Working with Riot.js opened my mind, it let me understand that even the most complex feature can be achieved with elegance and few code relying on the power of web components.

Riot.js was initially created by muut.com and developed by Tero Piirainen in 2015. I became the main maintainer of it while I was working on its second major release. Helped by an incredible international team of contributors, we were able to massively increase its user base (from 3k npm monthly downloads to 70k).

However I was unhappy with its original core design and with the new v4 version I took the time (almost 2 years) to completely rewrite and redesign the entire framework and all its ecosystem.

The Problem

This year (2019) web components support across browser vendors has massively improved but their API doesn’t seem to help much developers solving their simplest problems.

Frameworks like AngularJS, Ember.js and React.js seemed to simplify our life in the short term. However handling the amount of new concept and their convoluted APIs is a price that not every developer is willing to pay.

To solve this issue many other libraries like Vue.js and Svelte.js proved that you don’t need a complex API to develop beautiful interfaces. Being that true on one hand, on the other they add an incredible amount of magic to your code (reactive properties, Proxy, two-way-data binding, computed, observable…) binding you (and your mind) to specific framework idioms and meta programming techniques that might change on any major release. This is definitely not a future proof approach! Another problem is that even if these tools look simple at beginning, as soon as your projects starts growing, you will need to handle and understand many of the tricks they use under the hood. You will often need to deal with dirty hacks here and there to let your code running on several browsers.

The Solution

Riot.js 4 aims to be the tiniest, simplest and yet most predictable framework for web components. It is designed to offer you everything you wished native web components API looked like.

Having worked a lot with Vue.js during the last 3 years I am really impressed by the simplicity of its API.
Evan You is an incredible talented developer and I was able to take many ideas from Vue.js bringing them to Riot.js 4.

I avoided any sort of magic or asynchronous rendering strategy to manage the Riot.js components. Observables, two way data bindings and “short cuts” meta programming techniques have no place in Riot.js 4.
The components interface is transparent and explicit and there are no Riot.js ways to achieve your goals: you can develop your components as you prefer.

The result is a beautiful API that will be beloved by functional programmers (like me) and at same time it's impressively simple.

Let’s have a look for example at a component skeleton:

Skeleton of a Riot.js 4 component

The code above is self explanatory and it could be easily read by any developer without having to guess what it does.

The Rewrite

Riot.js 3 was ok and worked pretty well in many production environments but there were issues I couldn’t solve without redesigning it. The old compiler was fragile because based on regular expressions (no real parser ¯\_(ツ)_/¯ ), the runtime expressions evaluation was hard to maintain and it couldn’t be optimized any further and the components syntax was not really Javascript™ compliant.

With the new version I’ve tried to fix all the above issues adding tons of new improvements.
With Riot.js 4 you will get all the following new features out of the box:

  • Precise source maps
  • Content Security Policy support
  • True pure Javascript expressions
  • Better <slot>s support
  • Better compatibility with other languages like Typescript
  • Modern browsers support (NO internet explorer)
  • ES2016 Javascript modules
  • 5x performance boost
  • Stabler SSR + HTML hydration
  • 6kb Library size

Of course all these features came with a cost, your old components will not work in Riot.js 4

The old codebase didn’t allow me enhancing the framework any further and I had to take a decision: I could either rewrite the whole library ecosystem with the risk of loosing part of its community, or I could just leave the maintenance of the old code to someone else. I chose the first option and I couldn’t be happier about that, because by choosing that path I have learnt much more than I though.
Here you can check the list of the new Riot.js ecosystem packages I have (re)written for you:

Of course you don’t need to migrate you old application to Riot.js 4 but if you want to know how to do so you can read the migration guide.

The New Look

Riot.js logo was updated thanks to the community help

Designed by https://github.com/nibushibu

I have designed also a new website and the old one was migrated here. I will accept pull requests to improve the documentation and fix the typos so please help me on that.

The Roadmap

There is still tons of work to do…

I am focused on making the new API as stable as possible and building new features on the top of the new ecosystem. I will still be supporting Riot.js 3 for security patches but Riot.js 4 is the future and I will mainly work on it.

The Conclusion

Riot.js is not backed by any big company, it’s just me working alone on ~30 Javascript modules during my spare time. I’d love to work part time on the project but for that I will need your help. It would be great to get someone else on board as contributor working on the Riot.js ecosystem as well, so please if you think that you might be the right person for it let me know it.

Love or hate it, Riot.js 4 is here to stay. I will do my best to keep the framework as simple as possible without bloating its API with unnecessary stuff. My goal was to create a clean and maintainable software without the uncompelling need to compete with anyone else, it took almost 2 years but in the end I made it!

If you liked what you have just read and you want to learn a bit more about the framework you can start by reading its documentation on the official Riot.js website.

Let’s riot!

The Credits

Many thanks to:



Gianluca Guarini

I code stuff for living — Riot.js Maintainer — I like javascript, haskell and golang