Goes through the doc, learns about “bower.json”, the manifest, and the “dist” dir
Adds the library via Bower (let’s consider Lodash for example), saving it in the config in the process (pretty easy to figure out this first step)
Runs the Gulp script
Checks the “dist” folder. Sees jQuery, Modernizr, but no Lodash. Wonders why and gets confused. Also wonders why the Bootstrap JS file isn’t there (which is one of the JS libraries), and gets more confused
Re-reads “gulpfile.js”, notices that things about a manifest are mentioned
Opens “manifest.json” and notices that jQuery and Modernizr are mentioned. Wonders if he should add in that file an entry for the Lodash library that he wants to add, and gets confused
With the prospect of “lodash.js” being added to the “dist” folder when this will all work in the end, he thinks that this future “dist/lodash.js” file will have to be imported somewhere in the PHP code
Finds that this PHP code is in the “assets.php” file, reads the useful documentation section at the top about what this file does. Yet still wonders why “modernizr.js” and “main.js” are mentioned, but not “jquery.js”, and gets confused. (this is a bug btw: a line for jQuery should be added to that documentation comment).
After some time, ends up opening “dist/main.js” and notices that Lodash was actually added in that file since the last Gulp run.
Wonders why Lodash is added inside “main.js”, whereas jQuery and Modernizr are in their own file, and gets confused.
Finally understands how this all works. He deletes the “dist” folder, removes all declarations of libraries from “manifest.json”, reruns Gulp, realises that every single library JS code is in “dist/main.js”, and is happy.
This is how it could have gone instead:
Goes through the doc, learns about the existence of “bower.json” and the “dist” dir. The manifest is barely mentioned, because as a developer you probably won’t need to touch it.
Adds the library via Bower (let’s consider Lodash for example), saving it in the config in the process (pretty easy to figure out this first step)
Runs the Gulp script
Notices that the code of the Lodash library is added to “dist/main.js”
Doesn’t need to wonder about updating PHP imports, because no new file is added
So what do you think of merging all the JS code in “dist/main.js” and removing libraries from the manifest? Would simplify everything IMO.
I’m a little confused. This is actually the intended and expected functionality of the build process. You certainly do not need to add every new JavaScript file from your Bower packages in manifest.json.
Alright, but Modernizr and jQuery have a special treatment, because they aren’t added to main.js, that’s why it gets confusing when a new user wonders what to modify in the code in order to add a library to the project.
If all Bower libraries were built the same way into the dist folder (from the main property of the Bower config), including jQuery and Modernizr, it would avoid any doubt on how Bower libraries are added to a project.
Don’t you think?
By the way, I realised in the meantime that the manifest is useful, but not for libraries available in Bower. And both jQuery and Modernizr are available in Bower.
Well at the minimum, jQuery is not included because if you have Soil installed then jQuery is loaded via the Google CDN.
For Modernizr, I’m not sure why it could not be added to main.js off the top of my head, it may be left over from when Sage used Grunt and Modernizr was being dynamically generated. It seems like at one point Modernizr suggested keeping it separate from other .js files, but I’m having trouble finding that quote.
In any case, if you want either or both added to main.js, then remove them from manifest.json.
I had overlooked the replies. I’m now more experienced with Sage, having finished my first project. I still think exactly the same thing as when I initially posted: that seeing some Bower libraries mentioned in manifest.json confuses us theme developers.
A few things have changed since my post. First of all, as of today, the latest version of Modernizr available on Bower (modernizr#3.1.0) doesn’t contain modernizr.js any longer. In short: it’s unusable via Bower. Right now, if I understand things correctly, Modernizr V3 is designed to be custom built. So this means that the current build process of Sage is not compatible with the latest Modernizr. The way I updated my theme to use the latest Modernizr was by updating my manifest.json to the following:
Therefore, using the latest Modernizr can only be done if it’s not loaded from Bower. I even think Modernizr could be removed altogether from Sage (removed from bower.json). So “problem solved”, kind-of.
Remains the case about jQuery. Kalen you mention that jQuery is loaded by Soil, and therefore you don’t want it in main.js. I now understand better why that Bower library is mentioned in manifest.json. But I see this as an architecture mistake: the architecture of the main product (Sage) is influenced by an optional addon (Soil).
In any case, for those who don’t really care if they use the latest version of Modernizr, and are fine with V2.8.2, then what about simply removing that entry from manifest.json? It works just fine if it ends up in main.js with the other Bower libs.