Javascript documentation is out of date and minimal

A May Of WTFs
#1

When Rails 6 released I went out to:

To figure out all the changes with Javascript. Instead it still has lines like:

“Rails ships with CoffeeScript by default, and so the rest of the examples in this guide will be in CoffeeScript.”

There’s not even a mention of Webpacker on the page. I ended up buying two different books on rails just to read the sections the authors had on using Javascript with rails… and both books had different ideas on the subject.

The Turbolink section on the page is also very sparse. I haven’t tested it with Rails 6 but in Rails 5 getting Turbolinks to work with certain Javascript libraries lead to many headaches. To the point where I’ve heard many people just say turn Turbolinks off if you use more than a little Javascript.

I see people leaning more towards rails as a server side / api language and less for the front end side of things and I think this contributes to that feeling.

But let me add that I’m saying this because you asked for my WTF moments. I really appreciate all the hard work the rails team puts into the project. I have been programming in rails for years and it is a beautiful framework even with the occasional bumps in the road.

6 Likes
#2

FWIW there is an issue on this from March, though I don’t think anyone has taken it up [guides] Explain how to use Webpacker for Javascript, or mention it exists · Issue #38767 · rails/rails · GitHub

It seems that the edge guide has already been updated to mention webpacker’s dependencies in at least the getting started guide, but not the working with JS guide.

I definitely agree the guide needs to be updated :slight_smile:

#3

<3 thanks for reporting this!

You’re not the only person who’s brought this up, and we’re coordinating efforts to fix the situation in this thread: Sprockets abandonment. If you have any time or energy to help out, then I’m sure it would be welcome!

#4

My experience here is that this is definitely a pain point. I have grown to love developing with rails-ujs, turbolinks and stimulus, but its been a bumpy road getting there (whereas I’d describe learning say, ActiveRecord, as relatively smooth). A stackoverflow question I asked and answered in 2016 about how to opt out of Turbolinks caching for jquery plugins without a nice cleanup/destroy method is a good example of this frustration. We are using Rails, an awesome fullstack web framework that includes things like Turbolinks by default - but on the Rails side there is very very little documentation about it. And then you go to the Turbolinks or the Stimulus documentation, and it is fantastic, but it is not allowed to document things for the Rails audience because they are supposed to be good open source js frameworks that don’t show favoritism to Rails.

Here is the stack overflow question, which is back when I still used coffeescript because it was the Rails default. https://stackoverflow.com/questions/39627881/jquery-plugin-initialization-on-browser-back-button-for-turbolinks-rails-5/39801052#39801052

1 Like
#5

It seems like a lot of the activity on the Sprockets abandonment thread is about configuration and setup of the asset pipeline (including its documentation), I took this WTF as more about javascript usage post setup.

Edit: JK - the OP mentions lack of Webpacker mention specifically, but also Turbolinks.

#6

@fordfischer thanks for catching, you’re totally right!

@rose, I’m sorry that my first response came from a misread of your message.

I really appreciate both of you pointing out the holes in the Rails documentation here, especially because enabling people to do non-SPA frontends is something I care deeply about.

1 Like
#7

I’d like to point out a related concern - beginner friendliness.

In contrast to how earlier versions of Rails started me on simple little sprinkles of jQuery, where / how I should start with JS in Rails 6 is pretty cryptic. Granted, teaching JS isn’t quite Rails’ responsibility, but it’d be nice to have a friendly ramp to the right resources.

1 Like
#8

Exactly. Rails is often taught as the most accessible way to get into web development - what used to be a sprinkle of jquery, is now basically, “figure it out on your own”. I think that’s a shift in the wider web development world, not Rails specifically, but since we aren’t going back to a world where a little jquery is all anyone expects, it would be great to have a resource here to point new developers in Rails friendly directions.

It might just be compiling further resources along the lines of “Hi new web developer! There are a million ways to incorporate JS into your Rails app, but here are some resources for ways that have led to developer happiness for many in the community” Just collecting stories and patterns that a new developer could emulate without having to learn React/Vue/Ember/Angular/etc… would be a big help.

#9

@DHH What are the plans for documenting Turbolinks 6 & particularly for documenting how it integrates with Rails? I’m leery of a huge documentation push now given how many things will be changing when T6 lands.

There might be potential in involving the community in T6 documentation pre-release, and using that as a site for evangelism around Turbolinks (and around tightly integrated client-server approaches more generally.)

I’d be happy to step up as a champion for that (after May) if no one else does. I suspect @Noel_Rappin might also be able to contribute.

1 Like
#10

Yes, I would be both willing and able

#11

TL6 isn’t timed with a specific Rails release for the moment, so when we’re ready to share the work, we can definitely do a bunch of joint documentation. Especially around the Rails integration. But we gotta finish up the basic works first. Lots of stuff going to spill out of this (like alleviating the need for Rails UJS entirely).

2 Likes
#12

I would love more docs on how JS works in Rails. It’s pretty much a mystery to me and I just try to not touch it once I get it working. Why do I need to yarn install? What is yarn (I worked that out, but it was just dumped there one day)? What is package.json? What do the JS files do in the app, and why are they in the locations they are in?

I want to use minimal JS in my app with Stimulus, and I want my assets fingerprinted and compressed, but I feel like I’ve had a whole ton of Javascript stuff I don’t really want or know how to deal with dumped on me to do it.

5 Likes
#13

This one is definitely my WTF too - the only headache I’ve found with 6 has been understanding the whole webpacker environment and best practices. Hard to find definitive docs/guides.

Other than that, have to say, not sure what all the fuss is about :slight_smile: … Rails is still most awesome and I love working with it more than ever

1 Like
#14

For visibility, there’s a coordinated effort to write a Rails guide for Webpacker in this thread: JavaScript Documentation Coordination

2 Likes
#15

Particularly since most JS libraries say to use npm and yarn seems to be preferred for Rails.

More Resources

Keep up to date with Rails on Twitter and This Week in Rails

Policies: Conduct, License, Maintenance, Security, Trademarks