Semantic naming in Stimulus.js

Vitaliy Emeliyantsev — Sat, 02 May 2020 13:28:50 +0000

TL;DR: You can use data-controller="PascalCase" and controllers/PascalCase_controller.js naming in Stimulus. It's not a hack, Stimulus supports it out of the box.

Stimulus Reflex is the topic #1 this week. Link #1 in Ruby Weekly, multiple mentions in ruby chats, publication on DEV. I'm so happy for the guys, who created it. And there is one thing I want to talk about. Stimulus Reflex not only gave us effective way for creating reactive apps, but the way to properly name Stimulus controllers.

I love Stimulus concept, and have been using it since its very first public release. But one thing I truly hate and despise the way Stimulus developers and docs writers are naming their controllers.

In ruby world we have snake_case filenames and PascalCase classnames. It's a general convention and very clear to the community.
In ES6 world (React.js for example) we have both PascalCase filenames and classnames. It is even better and more semantically clear.

Now, what do we see in Stimulus docs? data-controller="hello" and hello_controller.js – "Ok, I see, lowercase controller name plus _controller suffix for filename – Easy Peasy."

But what about multiple words controllers? Should I write my_custom_input like in ruby, or MyCustomInput like in ES6? Let's read the docs and see: data-controller="content-loader" and content_loader_controller.js. Wait, WHAT??? How am I supposed to remember it? kebab-case for naming controllers in views and snake_case for filenames? Why??? 🤔

And every time I needed to add a new Stimulus controller (sometimes in a new project), I had to look for my previously added controllers and even google proper naming in internet. And that made me cry every time. 😢

But this week I met Stimulus Reflex. And guess what, Reflex author writes all reflex names with PascalCase. Whaat? 😲 But there is a Stimulus under the hood, right? And you tell me, I can use PascalCase in Stimulus?

Let's visit Stimulus github repo, search for code that scanning controllers folder. Here it is:

export function identifierForContextKey(key: string): string | undefined {
  const logicalName = (key.match(/^(?:\.\/)?(.+)(?:[_-]controller\..+?)$/) || [])[1]
  if (logicalName) {
    return logicalName.replace(/_/g, "-").replace(/\//g, "--")
  }
}

So what does Stimulus do. It scans folder for filenames including ANY cased string plus -controller or _controller suffix. After that Stimulus replaces all dashes with hyphens. That's the reason why you must use kebab-case in controller names inside views.

But the most important insight is that you can write PascalCase_controller.js filename, and use PascalCase controller name inside views. Or camelCase_controller.js and camelCase in views. Or even kebab-case-controller.js and kebab-case in views. It's up to you. I prefer PascalCase.

After so many years I finally have found a way to semantically name Stimulus controllers. It works out of the box, and it worked like this all the time. But because of official docs, every new developer is faced a naming problem. Now it's finally over. And thanks to Stimulus Reflex for that.

Forem: Vitaliy Emeliyantsev

Semantic naming in Stimulus.js