Support for Modules

The build script by default will concatenate and compress all the Javascript code not in the /js/libs folder and create a mangled file name for the now-combined Javascript file. This is for cache-busting purposes, i.e. you can configure your web server to cache this file on the clients for efficiency. This is a really great thing because users won't have to ever download that file again. But what if you change your code? If you do, the build script will generate a different mangled file name so users will pick up your latest-greatest work.

So by default, the build script puts most of your code in this single, huge Javascript file. But what if you are using a lot of Javascript, such as with a client-side framework like Backbone or Knockout? These frameworks can cause you to write a LOT of Javascript, much of it page or module-specific.

For example a travel web site written with Backbone.js might have a page to show hotel listings, and have some Javascript like this for the page:

SrchResultsModel.js  -- data model for search results
SrchResultsRouter.js -- a router-dispatcher for navigation or hash events
SrchResultsView.js   -- render and manage some HTML display

This code in turn might represent one panel (the search results) of a larger page, which might include other components such as a panel showing weekly specials, a small survey form, and the overall page "frame". Each of these elements could very well each have multiple Javascript files.

SpecialsModel.js        SurveyModel.js          FrameModel.js
SpecialsRouter.js       SurveyRouter.js         FrameRouter.js
SpecialsView.js         SurveyView.js           FrameView.js

Maybe for your project it makes sense to tie each of these components' files into one-per-component, leaving you with:

SrchResults.js     Specials.js     Survey.js    Frame.js

That's not bad, but let's say for the sake of argument that these 4 files are only useful on some, but not all of your application's pages. Across your whole application you may have dozens of files like this, but each page may only need a few of them at a time. For this kind of project it may not make sense to mash everything together in one mother-of-all-Javascript files. We need something a little more granular.

Enter the /js/modules directory. (To be clear, "modules" in this context is just a packaging term--not a true module in the sense that a tool like require.js would define them.) The intent of the /js/modules directory is to hold files that will be minified by the build script, but not concatenated together, allowing you some additional granularity. So for our example above I might create a directory structure like this:

/js/modules/components/Survey.js
/js/modules/components/Specials.js
/js/modules/components/SrchResults.js
/js/modules/Frame.js

The organization under /js/modules is purely arbitrary. When the build script runs, everything works as usual except that files in the new /js/modules directory will be minified but otherwise be left alone. The /js/modules directory name will be name-mangled for cache-busting purposes for the reasons described above. By default script.js and style.css get the same treatment by the build script, so this is merely extending the idea to the /js/modules directory. After running the build script you might see something like this in your publish directory:

/js/69db2Qrt

Ok so now that you have put your module Javascript code in /js/modules, you'll use it as any other Javascript file in your HTML pages:

<script defer src="js/modules/sample_module.js"></script>

The build script modifies references to the /js/modules directory just like it does for script.js and style.css. It might look something like this after running build:

<script defer src="js/69db2Qrt/sample_module.js"></script>

How (or if) you use the modules feature is up to you. If you need it, this feature will allow you to have more control over which Javascript code gets bundled into the global script.js file and which code is minified but otherwise left alone.