Semantic naming in Stimulus.js

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.