Rails: Asset Pipeline Lesson

[crespire]

Describe your suggestion

I wanted to start a conversation about re-writing the Rails Asset Pipeline lesson(s?), as there have been some big changes in the space and more on the way in the future with propshaft.

Right now, the asset pipeline lesson structure covers Rails 6 stuff first, then introduces Rails 7's import maps.

Here's my proposal on how we should change the lessons:

• Move webpack and webpacker discussion out of the Asset Pipeline lesson. This content should be moved into a second lesson which covers various common Rails asset pipeline configurations in a section called Asset Pipeline Configurations for Rails 6 or similar.
• The current Asset Pipeline lesson should be a more general introduction and discuss the tooling and current recommended/default approaches to serving assets in a modern Rails application. I think that means we should probably discuss what Sprockets is and how it relates to Webpack/Webpacker, esbuild and importmaps, then break down those options and their differences. Currently, the lesson is very general in its content, then talks at length about webpacker with anote that the Rails 7 stuff is in the next lesson.
• The second lesson, currently focused on import maps only, should be re-written to speak about specific configurations that are popular/standard now. There is some discussion to be had here on what we should discuss in depth vs just mention. I believe we should highlight the different combinations available, chiefly:
  • In Rails 7, a setup with Sprockets plus importmaps for Javascript - this is the default rails new setup
  • In Rails 7, a setup with Sprockets plus esbundling for Javascript - I believe this is the default setup for any of the alternate options like -c tailwind
  • In Rails 6 (default) and 7 (option with jsbundling), Sprockets with webpacker (shakapacker) for Javascript - I feel strongly this option should not be recommended for Rails 7, but recommended as the approach for Rails 6 (just due to how the rails new is set up). My view is that if we encourage folks to use a bundler in Rails 7, it should be esbuild via jsbundling-rails.

I spoke with @kobaltz about including his excellent "Demystifying the Asset Pipeline" Drifting Ruby episode and he has graciously agreed to allow us to link it as an additional resource. I feel strongly that, before we do that, we should update the content so it aligns more with what is currently prevalent/available.

Path

Ruby / Rails

Lesson Url

https://www.theodinproject.com/paths/full-stack-ruby-on-rails/courses/ruby-on-rails#assets-and-navigation

Checks

• [X] I have thoroughly read and understand The Odin Project Contributing Guide
• [X] Would you like to work on this issue?

(Optional) Discord Name

crespire#8269

(Optional) Additional Comments

No response

[KevinMulhern]

Thanks for the detailed write up @crespire 💪

Totally agree theres a lot we can do a lot to improve this area. I'll have a think about this; and drop in some thoughts later next week.

But to start, and simplify things. We should drop any remaining Rails 6 related asset stuff. Learners don't need it in the context of our course so it just muddies the water.

[crespire]

Thanks for the detailed write up @crespire 💪

Totally agree theres a lot we can do a lot to improve this area. I'll have a think about this; and drop in some thoughts later next week.

But to start, and simplify things. We should drop any remaining Rails 6 related asset stuff. Learners don't need it in the context of our course so it just muddies the water.

I would love to at least keep some brief mention of Rails 6 and pre stuff in the context of "In the past, this is how it was done, so here's a quick run through in case you work on an app like this." Let me know your thoughts on that as well!

[ChargrilledChook]

@crespire I agree with @KevinMulhern , I would prefer to simplify and align with the official / recommended approaches.

I don't think it would hurt to mention previous tools, but I think teaching them in addition is going to confuse people more than help them. Given we specifically tell people to install Rails 7 we should focus our support there.

Happy to hear your thoughts if you feel strongly about it though

Otherwise sounds like a great idea 🚀

[crespire]

Okay, I will keep the old stuff to a minimal blurb to focus on the Rails 7 content, and if the blurb is too long, we can always shop it after a first draft!

[KevinMulhern]

Sorry for the delay and thanks again for getting this discussion going @crespire. After looking over it all, I think, perhaps, the biggest problem we have is everything is mixed together. It makes it really difficult to figure out the reason we have the different tools and by extension where the boundaries are between them.

To be fair, we didn't know where everything was going to land when updating the course for Rails 7. But now it's been out a while, we can optimize.

Whats the reason for all the different tools?

Mostly writing the following out for my own benefit to get things straight in my head lol.

What finally made it all click for me, was understanding the high level problems each tool is trying to solve:

The Asset Pipeline

Does three main things:

• Concatenates many files into one
• Fingerprints those files for caching
• Transpiles some higher level languages like Sass, coffeescript down into vanilla css/js etc.

The problem with the asset pipeline, and why it’s being replaced with Propshaft and JS/CSS bundling is primarily because of the transpiling features of sprockets. The asset pipeline was constantly having to play catch up with all the new and popular frontend tooling constantly coming out.

So instead of the asset pipeline handling CSS/ JS tooling, it will now delegate to the new gems…

JS-Bundling

• Use whatever external JavaScript bundler you want with Rails - Webpacker, esbuild etc
• It should make Rails more flexible by being able to support new JS tooling when it arises.
• As far as the asset pipeline is concerned, the primary thing the external tool needs to do is output its final packaged JS file to /app/assets/builds/ so the asset pipeline can then deliver it the browser.

CSS bundling

• You can use whatever external CSS tooling you want, - SASS, Tailwind, Bootstrap
• Same idea as JS-bundling, makes Rails more flexible to new CSS tooling.
• As far as the asset pipeline is concerned, the primary thing the external tool needs to do is output its final packaged CSS file to /app/assets/builds/ directory so the asset pipeline can then deliver it to the browser.

Import Maps

• Removes the need to have NodeJS as a dependency.
• But:
  • Has compatibility issues with Safari
  • Many popular packages won't work with it, particularly any that come bundled with default CSS.

---

How we could restructure

I think most of the content we have is still useable. With a bit of moving around to make the responsibilities and boundaries of the different tooling clearer and tightening up content we’ll be in much better shape.

This is how I think we could restructure things so they flow better:

Asset Pipeline Lesson

• Rewrite to make it more practical for learners
• The first thing learners will want to do with assets in their early projects is make them look decent with CSS and images, so that should be the focus with this lesson.
• By the end of the lesson, learners will be able to:
  • Add vanilla CSS to their projects
  • Add images to their projects and use image helpers
  • Have a basic understanding of why the asset pipeline concatenates files and fingerprints for caching

With that in place, we’ve introduced learners to assets in Rails and have a solid foundation we can then build upon with…

Section: Working with JS in Rails

• Having this all in one section allows us to guide learners through the choices without the huge amount of context switching involved in it being broken up between sections as it is currently.
• To make things easier for the learner, we can afford to be opinionated. I agree with you, we should recommend JS-bundling with esbuild over the other options. I think that should the key takeaways for the learner by the end of the section.
• Where should this section be in the course? What is the first project learners can apply this stuff to? Private events?

It would include these lessons:

Stimulus JS

• We can lead with the Stimulus JS lesson
  • It works out of the box with Rails, learners don't need to know anything about the JS tooling first.
  • It will give us something to work with when demonstrating how the tooling works in the next lessons
• We could change the examples to something more practical learners will almost always need in their projects
  • Maybe a show/hide toggle?

Import Maps

• Demonstrate how it works by pulling in a third-party library learners can use in the stimulus controller they made in the previous lesson
  • We're currently using React in the examples - which isn't great (jsx won't work with import maps)
• Explain the advantages and trade offs involved with import maps.
• Side note. I considered leaving this lesson out altogether to simplify things. But because it's the default, we should at least make learners aware of it. We don't need to go super deep with it.

JS Bundling

• Demonstrate how it works using the same example from the import maps lesson.
• Recommend learners use JS-bundling with esbuild over import maps for their projects.

Section: Turbo

• We’ll need to break out a new section for Turbo if we do the above restructuring
• We only put the Turbo Drive lesson early in the course because of the issues with Hotwire and Devise. But now that Devise works out of the box with Hotwire, we can move that lesson to later in the course and have all the turbo lessons in one place
• Placement in the course? - same as where the Rails Sprinkles section currently is?

CSS Bundling Lesson

• CSS bundling is kind of the odd one out in terms of where it should go.
• Learners will only need to use it if they want to use a preprocessor like Sass to write their CSS, or if they want to use a framework like Tailwind. But we encourage learners to use vanilla CSS throughout the curriculum so they can get proficient with it.
• I think we could add this to the catch all Mailers and Advanced Topics section, so learners can use it with their final project if they want.

---

Sorry @crespire, this got a lot longer than I intended. I know it's a lot to unpack and probably much bigger in scope than you might have been thinking.

If we were to even just restructure the lesson placement similar to the above; and make it clear within each lesson, the reason for that tools existence / problems it is trying to solve. It would go a long way towards making this stuff easier to grok imo. That would maybe be a good middle ground.

[crespire]

Lots of good stuff here! I'll have a think about some of the Qs you've raised, but I am happy to take on the project. I think it would be worthwhile not only for curriculum clarity, but also for my own learning to get a bit deeper with these things.

I'll have some responses and comments soon!

[crespire]

I've had a second read through, and while there is a big scope of work, I'm happy to proceed in a phased manner so we can make sure good changes can have an impact sooner.

How would we feel about the first step being a general "Here are all the tools" kind of re-write for the Asset Pipeline lesson?

I think most learners at this point are probably just using rails new so it's not completely critical or blocking if we do a high level review of the asset pipeline and its tooling without diving specifically into JS bundling/CSS bundling.

Then as a follow-on project, we can re-jig the other bits as you've suggested. I really like the revised structure here, just not sure we could do it all at once, unless we're willing to have it lag a little bit.

Let me know, I'd be happy to start on the first overview lesson re-write and maybe tweak some of the current stuff to flow better with the re-write once it's done.

[KevinMulhern]

Phased approach sounds great @crespire 💪 this should lend itself very well to being done over a few iterations.

How would we feel about the first step being a general "Here are all the tools" kind of re-write for the Asset Pipeline lesson?"

I think I have a good idea of what you're proposing for this. What are the high level things you think this should cover?

I think most learners at this point are probably just using rails new so it's not completely critical or blocking if we do a high level review of the asset pipeline and its tooling without diving specifically into JS bundling/CSS bundling.

This is exactly my line of thinking too. If students can't use it in the next available project, it's not worth the student spending time learning it right now. It won't be useful nor retained if it can't be put into practice at the next available opportunity.

We can sometimes fall into the trap of trying to cover everything in a lesson and almost recreating documentation. Our best lessons cover only whats needed, respecting the learners time and ultimately providing a much better experience for the end user.

[crespire]

What are the high level things you think this should cover?

I think the outline you provided about the high level problems Asset Pipeline is trying to solve and how modern Rails does it with delegation to new gems is the way to go.

I'm not exactly sure how it will shake out, but happy to draft something up for review/workshoping. I just know as a learner that these lessons were very heavy and I felt like they were missing a lot of the big picture which meant the specific content lacked a lot of context.

[KevinMulhern]

leading with the high level problems it solves sounds great to me @crespire 💪 giving learners an understanding of "why this thing exists" will add a ton of context we didn't have before.

I'd be tempted to skip talking about the new gems in this lesson, just because it's early in the course and students won't need JS or external CSS tools for their first few projects. But, also more than happy to see what you put together if you feel including them will make this better.

The only thing I'd add is to have a practical outcome in mind with the revised lesson. "What will the student be able to do by the end of the lesson?" kind of thing. Part of what makes these lessons so heavy is theres a lot of reading and little doing imo.

For this, being able to add vanilla CSS and work with images with a new Rails app seems like the most appropriate outcome. They'll be able to put those skills into practice in the early projects in the forms and authentication section.

[github-actions[bot]]

This issue is stale because it has had no activity for the last 30 days.

[github-actions[bot]]

This issue is stale because it has had no activity for the last 30 days.