Stimulus 1.0: a modest JavaScript HTML framework that you already have

From the translator: David Heinemeyer Hansson wrote a small text about why he and his team Ruby on Rails developed their own Javascript framework. The original text is placed in the repository of the new project.

Updated February 4 : The original article was officially published on the Basecamp blog. Updated link to original from title

We write a lot of Javascript in Basecamp , but we do not use it to create "JavaScript applications" in the modern sense. All our applications render HTML on the server side, then we add javascript interspaces to revive them.

This is the path of the majestic monolith . Basecamp runs on a variety of platforms, including native mobile applications, with a single set of controllers, views, and models created under Ruby on Rails. Having a common interface that is updated from a single place is the key to ensuring that a small team works well, despite the many supported platforms.

This allows us to be productive, as in the good old days. A return to the days when a single programmer could make a lot of progress without getting stuck in layers of abstractions of distributed systems. The time before everyone began to think that the holy grail is to limit the server side to just producing JSON for Javascript applications on the client.

This does not mean that there is no point in such an approach for some people in some place. But as a basic approach to many types of applications, and of course, such as Basecamp, this is generally a regression in terms of simplicity and productivity.

Also, this does not mean that the distribution of single-page JavaScript applications did not bring any benefit. They brought speed, more dynamic interfaces and freedom from reloading the entire page.

We also wanted this feeling for Basecamp. To make it look like we followed the herd instinct and rewrote everything with client rendering or switched to completely native applications on mobile.

This desire led us to a double solution: Turbolinks and Stimulus.

Turbolinks up, Stimulus down

Before I go to Stimulus, our humble JavaScript framework, let me briefly retell the purpose of Turbolinks.

Turbolinks comes from the so-called pjax , developed in GitHub. The basic idea remains the same. The reason why a full page reload seems slow is not that it is difficult for the browser to process the HTML sent from the server. Browsers are really good and fast. The fact that HTML content is usually more than the same JSON is also unimportant (especially considering gzip). No, the main reason is that CSS and Javascript must be reinitialized and reapplied to the page. Regardless of whether the files are cached. This can be slow if you have a decent size of CSS and JavaScript.

To get around this reinitialization, Turbolinks keeps a constant process, just like single page apps do it. But, basically, this is an invisible process. It intercepts links and loads new pages on Ajax. The server still returns complete HTML documents.

This strategy alone can make most actions in applications really fast (if the server is able to answer for 100-200ms, which is possible with caching). For Basecamp, this accelerated page navigation 3 times. This gives the application the same sense of responsiveness and dynamism, which was for the most part the pros of one-page apps.

But Turbolinks is only half the story. Below the level of a full page change are minor updates within a single page. Showing and hiding elements, copying to the clipboard, adding a new entry to the todo list and other interactions that we do in modern web applications.

Before Stimulus Basecamp used a mixture of different styles and patterns to add these features. Part of the code was just on jQuery, a part of a similar size was on vanilla JavaScript and a somewhat large object-oriented system. All of them together worked through explicit event handling, based on data-behavior attributes.

It was easy to add a new code like this, but it was not a complete solution and we had several parallel existing self-made styles and patterns. This complicated the reuse of code and the training of new developers to some kind of unified approach.

Three main concepts in Stimulus

Stimulus wraps the best of these patterns in a modest little framework, spinning around three basic concepts: controllers (controllers), actions (actions) and targets (targets).

It is designed to progressively improve the HTML for which it is intended. So you can take a simple template and see what behavior affects it. Here is an example:

<div data-controller="clipboard"> PIN: <input data-target="clipboard.source" type="text" value="1234" readonly> <button data-action="clipboard#copy">Copy to Clipboard</button> </div> 

You can read this and get a pretty good idea of ​​what's going on. Even without knowing anything about Stimulus and looking at the code for the controller itself. It is almost like pseudocode. This is very different from reading a piece of HTML that has an external JavaScript file hanging event handlers here. It also provides entity separation that is lost in many modern JavaScript frameworks.

As you can see, Stimulus doesn't bother creating HTML. Rather, it hooks itself to the current HTML document. And HTML in most cases is rendered on the server either by loading the page (first run), or via an Ajax request that changes the DOM.

Stimulus focuses on manipulating an existing HTML document. Sometimes this means adding a CSS class that hides, animates, or highlights an element. Sometimes this means swapping elements in groups. Sometimes it means manipulating the content of an element, for example, converting a UTC time, which is cached along with the content, into local, shown to the user.

In these cases, you want Stimulus to create new DOM elements, and you are definitely free to do so. Maybe in the future we will even add some sugar to make it easier. But these are secondary scenarios. The main focus is on manipulation, not the creation of elements.

How Stimulus differs from mainstream JavaScript frameworks

This makes Stimulus very different from most modern JavaScript frameworks. Almost all of them are focused on turning JSON into DOM elements through some kind of pattern language. Most use these frameworks to generate a blank page filled exclusively with elements created via JSON-to-template rendering.

Stimulus also differs in matters of state. Most frameworks have ways of maintaining state inside JavaScript objects, so that they can render HTML based on this state. Stimulus is the exact opposite. The state is stored in HTML, so controllers can be thrown out between page changes, but they are re-initialized as soon as the cached HTML appears again.

This is a significantly different paradigm. I’m sure many experienced JavaScript developers who have worked with modern frameworks will be mocked. But no, leave me alone. If you are happy with the complexity and effort that is required to keep the app in the whirlpool, say, React + Redux, then Turbolinks + Stimulus will not like you.

But on the other hand, if you have a feeling that the thing you are working on does not require such a level of complexity and separation of applications, which is implied in modern technologies, then you will most likely find salvation in our approach.

Stimulus and similar ideas from the real world

At Basecamp, we have used this architecture on several versions of Basecamp and other applications for several years. GitHub used a similar approach with a wonderful effect. This is not just an alternative to mainstream understanding of what a modern web application looks like, but also surprisingly competitive.

In fact, this is similar to the secret ingredient that we had in Basecamp when we did Ruby on Rails. The feeling that today's popular approaches are unduly linear, so that we can do more with less effort.

Moreover, you do not even need to choose. Stimulus and Turbolinks work great in conjunction with other heavier approaches. If 80% of your application does not fit into a complex installation, try our two-component build for this. Then deploy heavy equipment for the part of the application where you really benefit from it.

At Basecamp, we make use of several more complex approaches where there is a need. Our calendar functionality uses client rendering. Our text editor, Trix, is a fully assembled word processor that would not make sense as a bundle of Stimulus controllers.

This set of alternative frameworks for weight loss as much as possible. To stay within the request-response paradigm for most interactions that work fine with this simple model. Then we turn to expensive instruments, where there is a sense to achieve the maximum effect.

First of all, it is a set of tools for small teams that want to compete in coverage with large teams that use more time-consuming, mainstream approaches.

Give him a chance!

Link to GiHub project