The Asset Pipeline documentation references vendor/assets, but after creating a new project, I only see vendor/javascript. Is the documentation incorrect or am I missing Vendor/Assets?

[EarningEvolved]

Hello All! I have an old Rails project I am converting over to the "latest" way of loading javascript/images/etc. I created a new project using rails new . git -d postgresql and proceeded to go through the newly created shell to see the various differences in how the project was set up. I clicked on the vendor directory and noticed the directory had a javascript directory. I assumed that folder holds the vendor specific javascript that needs to be added to the project and I went to the handy Asset Pipeline guide to read up on it. That guide is located here: https://guides.rubyonrails.org/asset_pipeline.html. The guide states, Pipeline assets can be placed inside an application in one of three locations: app/assets, lib/assets or **vendor/assets**.

The documentation goes on to state

Pipeline assets can be placed inside an application in one of three locations: app/assets, lib/assets or vendor/assets.
...
vendor/assets is for assets that are owned by outside entities, such as code for JavaScript plugins and CSS frameworks. Keep in mind that third party code with references to other files also processed by the asset Pipeline (images, stylesheets, etc.), will need to be rewritten to use helpers like asset_path.

Finally, the guide states

For example, these files:
...
vendor/assets/javascripts/slider.js

would be referenced in a manifest like this:
...
//= require slider

All of these things lead me to believe that the scaffolding didn't create the correct structure and it should be

• Vendor

•  Assets
  

•       Javascript
  

instead of

• Vendor

• Javascript
  

Although I know I can easily change the directory structure to be Vendor/Assets/Javascript, if a new user is following the guide and working to understand how the Asset Pipeline works and where their assets should go, this small error may add to their confusion concerning the correct way to set up their assets so the system will recognize them. This could also lead them to believe that the documentation is incorrect and possibly set their files up in a way that may/may not be recognized. I believe for consistency, the documentation and project scaffolding should match and Vendor/Javascript should be changed to Vendor/Assets to follow along with app/assets & lib/assets.

FYI - I'm using: Ruby - 3.1.2p20 (2022-04-12 revision 4491bb740a) [x86_64-linux] Rails - 7.0.3 Postgresql - 14.4 WSL2 Ubuntu 22.04 LTS

Thank you, in advance, for taking the time to review this.

[skipkayhil]

Hey @EarningEvolved :wave: thanks for raising an issue! The vendor/javascript folder is coming from importmap-rails

https://github.com/rails/importmap-rails/blob/624d7737cf50b31dd366ca578af3f2555ef5e8ed/lib/install/install.rb#L17-L19

(I haven't been able to find where vendor/assets used to be created yet, but can confirm it is not created with rails new anymore)

I agree that Asset Pipeline docs need some work, there's a WIP PR to update them with the new defaults: #45400

[EarningEvolved]

Skip, thank you for your reply! I've found some more issues with the documents that don't match with the scaffolding. For example, the scaffolding introduces link_tree and link_directory, but the actual documentation references require_tree and require_directory in the manifest. Which one is the formally correct one to use?

Initially, I just slammed my old code into a new project and got it working, but I used webpack to do it. I'm now going back and trying to really take out all of the things I included just because I didn't have time to devote to the update. I'm finding little things that don't match, but I would love to be part of the solution. If appropriate, can I keep this are open to ask you questions and, after I figure out if the scaffolding or the documentation is correct, submit them to you officially so the documents can be updated? I don't mind helping with the documentation, but I just need a sounding board to determine the right course of action first. If someone else is already doing this, then never mind.

[skipkayhil]

For example, the scaffolding introduces link_tree and link_directory, but the actual documentation references require_tree and require_directory in the manifest. Which one is the formally correct one to use?

They have slightly different purposes, see the directives section in the Sprockets README.

If appropriate, can I keep this are open to ask you questions and, after I figure out if the scaffolding or the documentation is correct, submit them to you officially so the documents can be updated?

Definitely feel free to open PRs. I think adding thoughts to #45400 would be very helpful as well as there's a lot of work to be done there.

[KarimElsayad247]

There happens to be another issue with the Assets pipeline guide: there's a part about auto-generating css/scss files when creating a controller with a generator, but this no longer happens as seen with with PR https://github.com/rails/rails/commit/d5b9618da1ac60c674e8a27c3ab4e33742e9aa9b

[rails-bot[bot]]

This issue has been automatically marked as stale because it has not been commented on for at least three months. The resources of the Rails team are limited, and so we are asking for your help. If you can still reproduce this error on the 7-0-stable branch or on main, please reply with all of the information you have about it in order to keep the issue open. Thank you for all your contributions.