Gruntfile.js

Tasks

The hello-world task that we’ve just seen serves as an example of a basic, stand-alone Grunt task. Such tasks can be used to implement simple actions specific to the needs of a single project that you don’t intend to reuse or share. Most of the time, however, you will find yourself interacting not with stand-alone tasks, but instead with tasks that have been packaged as Grunt plugins and published to npm so that others can reuse them and contribute to them.

Plugins

A Grunt plugin is a collection of configurable tasks (published as an npm package) that can be reused across multiple projects. Thousands of such plugins exist. In Listing 1-2, Grunt’s loadNpmTasks() method is used to load the grunt-contrib-uglify Node module, a Grunt plugin that merges a project’s JavaScript code into a single, minified file that is suitable for deployment.

Configuration

Grunt is known for emphasizing “configuration over code”: the creation of tasks and plugins whose functionality is tailored by configuration that is specified within each project. It is this separation of code from configuration that allows developers to create plugins that are easily reusable by others. Later in the chapter, we’ll take a look at the various ways in which Grunt plugins and tasks can be configured.

Maintaining a Sane Grunt Structure

The Gruntfile shown in Listing 1-7 is for a relatively simple project. We already find this example to be slightly unwieldy, but within larger projects we have seen this file balloon to many times this size. The result is an unreadable and difficult-to-maintain mess. Experienced developers would never write their code in a way that combines functionality from across unrelated areas into a single, monolithic file, so why should we approach our task runner any differently?

Managing Configuration

Task Descriptions

Asynchronous Tasks

Task Dependencies

Multi-Tasks

In addition to basic tasks , Grunt offers support for what it calls “multi-tasks.” Multi-tasks are easily the most complicated aspect of Grunt, so if you find yourself confused at first, you’re not alone. After reviewing a few examples, however, their purpose should start to come into focus—at which point you’ll be well on your way toward mastering Grunt.

In this example, our multi-task ran twice, once for each available target (mammals and birds). Notice in Listing 1-15 that within our multi-task we referenced two properties: this.target and this.data. These properties allow our multi-task to fetch information about the target that it is currently running against.

Multi-Task Options

Multi-task options provide developers with a mechanism for defining global options for a task, which can then be overridden at the target level. In this example, a global format in which to list animals ('array') is defined at the task level. The mammals target has chosen to override this value ('json'), while the birds task has not. As a result, mammals will be displayed as JSON, while birds will be shown as an array due to its inheritance of the global option.

The vast majority of Grunt plugins that you will encounter are configurable as multi-tasks. The flexibility afforded by this approach allows you to apply the same task differently under different circumstances. A frequently encountered scenario involves the creation of separate targets for each build environment. For example, when compiling an application, you may want to modify the behavior of a task based on whether you are compiling for a local development environment or in preparation for release to production.

Configuration Templates

Listing 1-19 shows a sample Gruntfile that loads the contents of the project’s package.json file using one of several built-in methods for interacting with the file system that are discussed in further detail later in the chapter. The contents of this file are then stored under the pkg key of Grunt’s configuration object. In Listing 1-20, we see a task that is able to directly reference this information through the use of configuration templates.

Command-Line Options

Providing Feedback

Handling Errors

Source-Destination Mappings

Many Grunt tasks that interact with the file system rely heavily on the concept of source-destination mappings, a format that describes a set of files to be processed and a corresponding destination for each. Such mappings can be tedious to construct, but thankfully Grunt provides helpful shortcuts that address this need.

As you can see, our project has an images folder containing three files. Knowing this, let’s take a look at a few ways in which Grunt can help us iterate through these files.

The combination of the src configuration property and the this.files multi-task property provides developers with a concise syntax for iterating over multiple files. The contrived example that we’ve just looked at is fairly simple, but Grunt also provides additional options for tackling more complex scenarios. Let’s take a look.

The expand option, when paired with the dest option, instructs Grunt to iterate through our task’s this.files.forEach loop once for every entry it finds, within which we can find a corresponding dest property. Using this approach, we can easily create source-destination mappings that can be used to copy (or move) files from one location to another.

Watching for File Changes

Let’s take a look at a few examples that demonstrate such workflows put into action.

Getting Started

One of the first things you’ll want to do is create a public GitHub repository in which to store your new plugin. The example that we will be referencing is included with the source code that accompanies this book.

Creating the Task

The output generated by our plugin’s file-report task is shown in Figure 1-1.

Publishing to npm

Subcommands

In their simplest form, generators act as configurable project templates that simplify the creation of new projects, but that’s not their only purpose. In addition to assisting with the initial creation of new projects, generators can also include other commands that project maintainers will find useful throughout development.

Yeoman Generators Are Node Modules

Sub-generators

The contents of our generator’s app folder are shown in Figure 2-2.

Once Yeoman has compiled a list of the various prototype methods that exist within our generator, it will execute them in the priority shown in the preceding list.

Defining Secondary Commands

The script shown in Listing 2-14 looks very similar to that shown in Listing 2-9, the primary difference being the use of Yeoman’s NamedBase class. By creating a sub-generator that extends from NamedBase, we alert Yeoman to the fact that this command expects to receive one or more arguments.

Composability

With the help of Yeoman’s composeWith() method, simple sub-generators can be combined (i.e., “composed”) with one another to create fairly sophisticated workflows. By taking advantage of this method, developers can create complex, multicommand generators while avoiding the use of duplicate code across commands.

Lastly, it is worth noting that if you are stuck somewhere when developing with Yeoman, or, let us say, your Yeoman generator does not seem to be functioning as desired, there is a built-in troubleshooting command that you can make use of to diagnose and figure out code issues, compatibility issues, and more:

yo doctor

Related Resources

Recovering from Errors

At this point, you are now familiar with some of the basic steps involved in interacting with PM2. You’ve learned how to create new processes with the help of PM2’s start command. You’ve also discovered how you can subsequently manage running processes with the help of commands such as list, stop, restart, delete, and show. We’ve yet to discuss, however, much of the real value that PM2 brings to the table in regard to managing Node processes. We’ll begin that discussion by discovering how PM2 can assist Node applications in automatically recovering from fatal errors.

If we were to start this application without the help of PM2 by passing it directly to the node executable, we would quickly find ourselves out of luck the moment our first error was thrown. Node would simply print the error message to the console before dumping us back to the command prompt, as shown in Figure 3-4.

Such behavior won’t get us very far in a real usage scenario. Ideally, an application that has been released to a production environment should be thoroughly tested and devoid from such uncaught exceptions. However, in the event of such a crash, an application should at the very least be able to bring itself back online without requiring manual intervention. PM2 can help us accomplish this goal.

In Figure 3-5, we remove our existing process from PM2’s list via the delete command and create a new instance of the poorly written application shown in Listing 3-3. Afterward, we wait several seconds before requesting an up-to-date process list from PM2.

Notice anything interesting here? Based on the values within the status, restart, and uptime columns, we can see that our application has crashed three times already. Each time, PM2 has helpfully stepped in and restarted it for us. The most recent process has been running for a total of 2 seconds, which means we can expect another crash (and automatic restart) 2 seconds from now.

PM2’s ability to assist applications in recovering from fatal errors in a production environment, while useful, is just one of several useful features the utility provides. PM2 is also equally useful within development environments, as we’ll soon see.

Responding to File Changes

Imagine a scenario in which you’ve recently begun work on a new Node project. Let’s assume it’s a web API built with Express. Without the help of additional tools, you must manually restart the related Node process in order to see the effects of your ongoing work—a frustrating chore that quickly grows old. PM2 can assist you in this situation by automatically monitoring the file structure of your project. As changes are detected, PM2 can automatically restart your application for you, if you instruct it to do so.

Figure 3-6 demonstrates this process. In this example, we first remove our currently running instance of my-bad-app. Next, we create a new instance of the application that was shown in our original example (see Listing 3-2). This time, however, we pass an additional flag, --watch, which instructs PM2 to monitor our project for changes and to respond accordingly.

As changes are saved to this project’s files, subsequent calls to PM2’s list command will indicate how many times PM2 has restarted the application, as seen in a previous example.

Monitoring Local Resources

Figure 3-10 demonstrates the output that is generated when PM2’s monit command is called. Here we see a continuously updated view that allows us to track the amount of CPU processing power as well as the amount of RAM consumed by each process being managed by PM2.

Monitoring Remote Resources

The information provided by PM2’s monit command provides us with a quick and easy method for monitoring the health of its processes. This functionality is particularly helpful during development, when our primary focus is on the resources being consumed within our own environment. It’s less helpful, however, as an application moves into a remote, production environment that could easily consist of multiple servers, each running its own instance of PM2.

PM2 takes this into account by also providing a built-in JSON API that can be accessed over the Web on port 9615. Disabled by default, the process for enabling it is shown in Figure 3-11.

In this example, we enable PM2’s web-accessible JSON API by calling the utility’s web command. PM2 implements this functionality as part of a separate application that runs independently of PM2 itself. As a result, we can see that a new process, pm2-http-interface, is now under PM2’s control. Should we ever wish to disable PM2’s JSON API, we can do so by removing this process as we would any other, by passing its name (or ID) to the delete (or stop) commands.

JSON Application Declarations

The application configuration file shown here provides PM2 with instructions on how to launch each of the applications included within this project. In this example, PM2 is instructed to restart each application if changes are detected to either’s file structure, or if they begin to consume more than 60MB of memory. The file also provides PM2 with separate environment variables to be passed to each process.

As expected, PM2 has created two instances for us, one for each of the applications referenced within our configuration file. As in previous examples, we can monitor the output that is generated with the help of PM2’s logs command (see Figure 3-13).

Zero Downtime Deployments

After launching an application in cluster mode, PM2 will begin forwarding incoming requests in a round-robin fashion to each of the eight processes under its control—providing us with an enormous increase in performance. As an added benefit, having our application distributed across multiple processors also allows us to release updates without incurring any downtime, as we will see in a moment.

As these steps take place, a brief period of downtime will be introduced, during which incoming requests to the application will be rejected—unless special precautions are taken. Fortunately, launching applications with PM2 in cluster mode provides us with the tools we need to take those precautions.

Previous examples have demonstrated the use of PM2’s restart command, which immediately stops and starts a specified process. While this behavior is typically not a problem within nonproduction environments, issues begin to surface when we consider the impact it would have on any active requests that our application may be processing at the moment this command is issued. When stability is of the utmost importance, PM2’s gracefulReload command serves as a more appropriate alternative.

When called, gracefulReload first sends a shutdown message to each of the processes under its control, providing them with the opportunity to take any necessary precautions to ensure that any active connections are not disturbed. Only after a configurable period of time has passed (specified via the PM2_GRACEFUL_TIMEOUT environment variable) will PM2 then move forward with restarting the process.

In this example, after receiving the shutdown message, our application responds by calling the close() method on the HTTP server that was created for us by Express. This method instructs our server to stop accepting new connections, but allows those that have already been established to complete. Only after 10 seconds have passed (as specified via PM2_GRACEFUL_TIMEOUT) will PM2 restart the process, at which point any connections managed by this process should already have been completed.

Figure 3-16 demonstrates the process by which this application can be started and subsequently restarted through the use of the gracefulReload command. By doing so, we are able to release updates without interrupting our application’s users.

Installation

The RequireJS script may be downloaded directly from http://requirejs.org . It comes in a few distinct flavors: a vanilla RequireJS script, a vanilla RequireJS script prebundled with jQuery, and a Node.js package that includes both RequireJS and its packing utility, r.js. For most examples in this chapter, the vanilla script is used. The prebundled jQuery script is merely offered as a convenience for developers. If you wish to add RequireJS to a project that is already using jQuery, the vanilla RequireJS script can accommodate the existing jQuery installation with no issues, though older versions of jQuery may need to be shimmed. (Shimmed scripts will be covered later.)

If you are working with CoffeeScript, RequireJS also comes with a plugin for CS integration. Internationalization plugin is also available and can be downloaded directly from https://requirejs.org .

Configuration

After the RequireJS script is loaded on a page, it looks for a configuration which will primarily tell RequireJS where script and modules live. Configuration options can be provided in one of three ways.

First, a global require object may be created before the RequireJS script is loaded. This object may contain all of the RequireJS configuration options as well as a “kickoff” callback that will be executed once RequireJS has finished loading all application modules.

The most important configuration property on this object, baseUrl, identifies a path relative to the application root where RequireJS should begin to resolve module dependencies. The deps array specifies modules that should be loaded immediately after configuration, and the callback function exists to receive these modules once they are loaded. This example loads a single module, quotes-view. Once the callback is invoked, it may access the properties and methods on this module.

Notice that the absolute path and file extension for the quotes-view module is omitted in the deps array. By default, RequireJS assumes that any given module is located relative to the page being viewed and that it is contained within a single JavaScript file with the appropriate file extension. In this case the latter assumption is true but the first is not, which is why specifying a baseUrl property is necessary. When RequireJS attempts to resolve any module, it will combine any configured baseUrl value and the module name, then append the .js file extension to produce a full path relative to the application root.

When the config01.html page loads, the strings passed to the quotesView.addQuote() method will be displayed on the page.

In this example a <script> block first uses the global requirejs object, created by the require.js script, to configure RequireJS by invoking its config() method. It then invokes requirejs to kick off the application. The object passed to the config() method resembles the global require object from Listing 4-4, but lacks its deps and callback properties. The requirejs function accepts an array of application dependencies and a callback function instead, a pattern that will become very familiar when module design is covered later.

The net effect is the same: RequireJS uses its configuration to load the quotes-view module, and once loaded, the callback function interacts with it to affect the page.

Application Modules and Dependencies

A module’s name is key. In Listing 4-9 a module name, m1, is explicitly declared. If a module name is omitted (leaving the dependencies and module closure as the only arguments passed to define()), then RequireJS will assume that the name of the module is the file name containing the module script, without its .js extension. This is fairly common in practice, but the module name is shown here for clarity.

The dependency list in Listing 4-9 identifies two other modules that RequireJS should load. The values d1 and d2 are the names of these modules, located in script files d1.js and d2.js. These scripts look similar to the module definition in Listing 4-9, but they will load their own dependencies.

Finally, the module closure accepts the output from each dependency module as function arguments. This output is any value returned from each dependency module’s closure function. The closure in Listing 4-9 returns its own value, and if another module were to declare m1 as a dependency, it is this returned value that would be passed to that module’s closure.

If a module has no dependencies, its dependency array will be empty and it will receive no arguments to its closure.

Once a module is loaded, it exists in memory until the application is terminated. If multiple modules declare the same dependency, that dependency is loaded only once. Whatever value it returns from its closure will be passed to both modules by reference. The state of a given module, then, is shared among all other modules that use it.

A module may return any valid JavaScript value, or none at all if the module exists only to manipulate other modules or simply produce side effects in the application.

Figure 4-1 shows the logical dependency tree created when these modules are loaded.

As application dependencies multiply, module pathing can become tedious, but there are two ways to mitigate this.

First, a module may use leading dot notation to specify dependencies relative to itself. For example, a module with the declared dependency ./foo would load foo.js as a sibling file, located on the same URL segment as itself, whereas a module with the dependency ../bar would load bar.js one URL segment “up” from itself. This greatly reduces dependency verbosity.

Second, modules may be named with path aliases, defined in the RequireJS configuration, as described in the next section.

Paths and Aliases

Assigning an alias to a module allows other modules to use the alias as a dependency name instead of the full module pathname. This can be useful for a variety of reasons but is commonly used to simplify vendor module paths, eliminate version numbers from vendor module names, or deal with vendor libraries that declare their own module names explicitly.

It is unlikely that jquery lives at the module root defined by the baseUrl configuration, however. It is more likely that the jquery script would exist within a vendor directory such as /scripts/vendor/jquery, and that the script name would contain the jQuery version (e.g., jquery-2.1.3.min), as this is how jQuery scripts are distributed. To further complicate matters, jQuery explicitly declares its own module name, jquery. If a module attempted to load jquery using the full path to the jQuery script, /scripts/vendor/jquery/jquery-2.1.3.min, RequireJS would load the script over HTTP and then fail to import the module because its declared name is jquery, not jquery-2.1.3.min.

Because module aliases take precedence over actual module locations, RequireJS will resolve the location of the jQuery script before attempting to locate it at /scripts/jquery.js.

Shims

Libraries that support the AMD module format are straightforward to use with RequireJS. Non-AMD libraries may still be used by configuring RequireJS shims or by creating shimmed modules manually.

The data/quotes module in example-003 exposes a groupByAttribution() method that iterates over the collection of quotes. It creates a hash where keys are the names of people and values are arrays of quotes attributed to them. This grouping functionality would likely be useful for other collections as well.

Fortunately, a vendor library, undrln , can provide a generalized version of this functionality, but it is not AMD compatible. A shim would be necessary for other AMD modules to use undrln as a dependency. Undrln is written as a standard JavaScript module within a function closure, shown in Listing 4-18. It assigns itself to the global window object, where it may be accessed by other scripts on a page.

By shimming non-AMD scripts, RequireJS can use its asynchronous module-loading capabilities behind the scenes to load non-AMD scripts when they are dependencies of other AMD modules. Without this capability these scripts would need to be included on every page with a standard <script> tag and loaded synchronously to ensure availability.

Running the web application in example-004 and then browsing to http://localhost:8080/index.html will display a list of quotes. Figure 4-2 shows the rendered page and Chrome’s Network panel in which all loaded JavaScript modules are listed. Note that the Initiator column clearly shows that RequireJS is responsible for loading all modules and that even undrln.js, a non-AMD module, is included in the list.

Loader Plugins

There are several RequireJS loader plugins that are so useful, they find a home in most projects. A loader plugin is an external script that is used to conveniently load, and sometimes parse, specific kinds of resources that may then be imported as standard AMD dependencies, even though the resources themselves may not be actual AMD modules.

i18n

RequireJS supports internationalization via the i18n loader plugin. (i18n is a numeronym, which means that the number “18” represents the 18 characters between “i” and “n” in the word “internationalization”.) Internationalization is the act of writing a web application such that it can adapt its content to a user’s language and locale (also known as National Language Support, or NLS). The i18n plugin is primarily used for translating text in a web site’s controls and “chrome”: button labels, headers, hyperlink text, fieldset legends, and so forth. To demonstrate this plugin’s capabilities, two new templates have been added to the example application, one for the page title in the header and one for the search field with placeholder text. The actual quote data will not be translated because, presumably, it comes from an application server that would be responsible for rendering the appropriate translation. In this application, though, the data is hard-coded in the data/quotes module for simplicity and will always appear in English.

The search.hbs template in Listing 4-31 has also been extracted from the index.html file and now accepts placeholder text for the search field as its only input. The search-view module has been adapted to use this template when it renders content in the DOM.

<!-- example-008/public/scripts/templates/search.hbs -->

<form>

  <fieldset>

    <input type="text" name="search" placeholder="{{searchPlaceholder}}" />

  </fieldset>

</form>

Listing 4-31

The search.hbs Template Will Display the Placeholder Translation

Listing 4-32 shows the new header.hbs template that will be rendered by the new header-view module. The template accepts a single input, the page title.

<!-- example-008/public/scripts/templates/header.hbs -->

<h1>{{pageTitle}}</h1>

Listing 4-32

The header.hbs Template Will Display the Page Title Translation

The header-view module in Listing 4-33 demonstrates not only how the template dependency is imported with the text plugin but also how a language module dependency is imported with the i18n plugin. The familiar loader syntax looks nearly identical: the plugin name followed by an exclamation mark and a module path relative to the configured baseUrl, in this case nls/lang. When a template is loaded, its serialized string content is passed to a module’s closure, but the i18n plugin loads a language module that contains translated text data and passes that module’s object to the closure. In Listing 4-33 this object will be accessible through the lang parameter.

// example-008/public/scripts/header-view.js

define([

  'quotes-state',

  'jquery-all',

  'handlebars-all',

  'text!templates/header.hbs',

  'i18n!nls/lang'

], function (quotesState, $, Handlebars, headerTemplate, lang) {

  // ...

});

Listing 4-33

The header-view Module Depends on the i18n Language Object

The language module is a regular AMD module, but instead of passing a list of dependencies and a closure to define(), a simple object literal is used. This object literal follows a very specific syntax, shown in Listing 4-34.

// example-008/public/scripts/nls/lang.js

define({

  root: {

    pageTitle: 'Ponderings',

    searchPlaceholder: 'search'

  },

  de: true

});

Listing 4-34

Default English Language Module

First, a root property holds the key/value pairs that will be used to fetch translated data when the plugin resolves the language translations. The keys in this object are simply keys by which the translated text may be accessed programmatically. In the search template, for example, {{searchPlaceholder}} will be replaced with the string value at the language object’s key searchPlaceholder when the template is bound to it.

Second, siblings to the root property are the various IETF language tags for active and inactive translations that should be resolved based on a browser’s language setting. In this example, the German de language tag is assigned the value true. If a Spanish translation was made available, an es-es property with the value true could be added. And for a French translation, an fr-fr property could be added, and so forth for other languages.

When a new language tag is enabled in the default language module, a directory corresponding to the language code must be made as a sibling to the module file. The nls/de directory can be seen in Listing 4-35.

├── nls

│   ├── de

│   │   └── lang.js

│   └── lang.js

Listing 4-35

Directory Structure for NLS Modules

Once the language-specific directory has been created, a language module file of the same name as the default language module file must be created within. This new language module will contain the translated content of the root property in the default language module only. Listing 4-36 shows the German (de) translation of the pageTitle and searchPlaceholder properties.

// example-008/public/scripts/nls/de/lang.js

define({

  pageTitle: 'Grübeleien',

  searchPlaceholder: 'suche'

});

Listing 4-36

German (de) Translation Module

When the default language module is loaded with the i18n plugin, it examines the browser’s window.navigator.language property to determine what locale and language translation should be used. If the default language module specifies a compatible, enabled locale, the i18n plugin loads the locale-specific module and then merges it with the default language module’s root object. Missing translations in the locale-specific module will be filled with values from the default language module.

Figure 4-3 shows how the quotes page looks when a Google Chrome browser’s language has been set to German.

Note

The window.navigator.language property is affected by different settings in different browsers. For example, in Google Chrome it only reflects the user’s language setting, whereas in Mozilla Firefox it can be affected by an Accept-Language header in a page’s HTTP response as well.

Cache Busting

Application servers often cache resources like script files, images, stylesheets, and so on to eliminate unnecessary disk access when serving a resource that has not changed since it was last read. Cached resources are often stored in memory and associated with some key, usually the URL of the resource. When multiple requests for a given URL occur within a specified cache period, the resource is fetched from memory using the key (URL). This can have significant performance benefits in a production environment, but invalidating cache in development or testing environments every time a code change is made, or a new resource is introduced, can become tedious.

Certainly caching can be toggled on a per-environment basis, but a simpler solution, at least for JavaScript (or any resource loaded by RequireJS), might be to utilize the RequireJS cache-busting feature. Cache busting is the act of mutating the URL for every resource request in such a way that the resource may still be fetched, but will never be found in cache because its “key” is always different. This is commonly done by including a query string parameter that changes whenever a page is reloaded.

Figure 4-4 shows that the bust parameter is indeed applied to each request initiated by RequireJS, even XHR requests for text resources like header.hbs.

While the usefulness of this feature is evident, it can also create a few problems.

First, RequireJS respects HTTP cache headers, so even if urlArgs is used as a cache-busting mechanism, RequireJS may still request (and receive) a cached version of a resource, depending on how cache is implemented. If possible, always serve the appropriate cache headers in each environment.

Second, be aware that some proxy servers drop query string parameters. If a development or staging environment includes proxies to mimic a production environment, a cache-busting query string parameter may be ineffective. Some developers use urlArgs to specify particular resource versions in a production environment (e.g., version=v2), but this is generally discouraged for this very reason. It is an unreliable versioning technique, at best.

Finally, some browsers treat resources with different URLs as distinct, debuggable entities. In Chrome and Firefox, for example, if a debug breakpoint is set in the source code for http://localhost:8080/scripts/quotes-state.js?bust=1432504595280, it will be removed if the page is refreshed, when the new resource URL becomes http://localhost:8080/scripts/quotes-state.js?bust=1432504694566. Resetting breakpoints can become tedious, and though the debugger keyword can be used to circumvent this problem by forcing the browser to pause execution, it still requires a diligent developer to ensure that all debugger breakpoints are removed before code is promoted to production.

Configuring r.js

A wide array of parameters may be passed as arguments to the r.js tool to control its behavior. Fortunately these parameters can also be passed to r.js in a regular JavaScript configuration file, which makes the terminal command significantly shorter. For nontrivial projects, this is the preferred configuration method and will be the only one covered in this chapter.

The code files in the example-010 directory have been moved into a standard src directory, and a new file, rjs-config.js, has been placed in the directory root. This file, unsurprisingly, contains the r.js configuration. Its contents are shown in Listing 4-38.

Developers who are familiar with build tools will immediately recognize the input/output pattern present in the configuration.

The appDir property specifies the project “input” directory, relative to the configuration file, where uncompiled source code lives.

The dir property specifies the project “output” directory, relative to the configuration file, where compiled and minified output will be written when the r.js tool runs.

The baseUrl property tells r.js where the project scripts are located relative to the appDir property. This should not be confused with the baseUrl property in the main.js file, which tells RequireJS where modules are located relative to the web application root.

The mainConfigFile property points to the actual RequireJS (not r.js) configuration. This helps r.js understand how modules are related to each other, and what module aliases and shims exist, if any. It is possible to omit this property and specify all of these paths in the r.js configuration, though that is beyond the scope of this example.

Setting the inlineText property to true ensures that all text files referenced with the text plugin prefix text! will be compiled with RequireJS modules in the final build output. This option is enabled by default but is explicitly set in this project for clarity.

By default, r.js will minify and copy all scripts (packed and unpacked) to the output directory. The removeCombined property toggles this behavior. In this case only the packed, compiled script(s) and any other scripts that could not be included in the packed output will be copied to the output directory.

The modules array lists all of the top-level modules to be compiled. Because this is a single-page application, only the actual main module needs to be compiled.

Finally, the optimize property instructs r.js to apply an uglify transform to all scripts, minimizing all JavaScript code.

Running the r.js Command

Several things immediately stand out in the public/scripts directory.

First, the require.js and main.js scripts are both present. Since these scripts are the only files referenced in index.html, their presence here is expected. Other scripts such as the quotes-view.js and quotes-state.js scripts are noticeably absent, but examining the content of main.js reveals why: they have been packed and minified according to the r.js build settings.

Second, the localization file nls/lang.js is now missing because it has been included as part of main.js. The nls/de/lang.js script still remains as part of the build output, though its contents have been minified. Any user browsing the example web page in the default locale will receive an optimized experience, as RequireJS will not have to make an external AJAX call to load the default language translations. Users from Germany will incur the additional HTTP request because the German localization file has not been included in the packed output. This is a limitation of the localization plugin that r.js must respect.

Third, the Handlebars templates, though compiled as part of the build output in main.js, have also been copied to the public/scripts/templates directory. This happens because RequireJS plugins currently have no visibility into the build process and therefore no method of honoring the removeCombined option in the r.js configuration file. Fortunately, because these templates have been wrapped in AMD modules and concatenated with main.js, RequireJS will not attempt to load them with AJAX requests. If deployment size is an issue for this project, a post-build script or task can be created to remove the templates directory if needed.

Fourth, the vendor/ventage directory has been copied to the build directory even though its core module, ventage.js, has been concatenated with main.js. While RequireJS can automatically remove individual module files (like ventage.js) after compilation, it will not clean up other files associated with a module (in this case, unit tests and package definition files like package.json and bower.json), so they must be removed manually or as part of a post-build process.

Watching for File Changes with Grunt

This simple approach typically serves most small projects quite well; however, as small projects gradually evolve into large projects, developers often grow frustrated, understandably, with the ever-increasing build times that accompany it. Having to wait several seconds before you can try out each of your updates can quickly destroy any sense of “flow” that you might hope to achieve. Fortunately, Browserify’s sister application, Watchify, can help us in these situations.

Watching for File Changes with Watchify

If Browserify (which compiles applications in their entirety) can be thought of as a meat cleaver, Watchify can be thought of as a paring knife. When invoked, Watchify initially compiles a specified application in its entirety; however, rather than exiting once this process has completed, Watchify continues to run, watching for changes to a project’s source code. As changes are detected, Watchify recompiles only those files that have changed, resulting in drastically faster build times. Watchify accomplishes this by maintaining its own internal caching mechanism throughout each build.

In this example, we wrap our browserify instance with watchify. Afterward, we recompile the project as needed by subscribing to the update event emitted by our wrapped instance.

Module Resolution and the NODE_PATH Environment Variable

In situations such as this, Node will first attempt to locate the referenced module within its core library. This process can be seen in action when loading modules such as fs, Node’s file system module. If no match is found, Node will then proceed to search for folders named node_modules, starting with the location of the module that called require() and working its way upward through the file system. As these folders are encountered, Node will check to see if they contain a module (or package) matching that which was requested. This process will continue until a match is found, and if none is found, an exception is thrown.

This simple yet powerful method by which module resolution occurs within Node revolves almost exclusively around the node_modules folder. However, Node provides an often-overlooked method that allows developers to augment this behavior by defining additional folders within which Node should be allowed to search for modules, should the previous steps turn up empty-handed. Let’s take a look at this chapter’s path-env project, which demonstrates how this can be accomplished.

Take note of this example’s lack of relative module references. For example, notice how this project’s main script, bin/index.js, is able to load a custom module responsible for initializing Express via require('app/api');. The alternative would be to use a relative path: require('../lib/app/api');. Anyone who has worked within complex Node applications and encountered module references along the line of require('../../../../models/animal'); will quickly come to appreciate the increase in code clarity that this approach affords.

Dependency Management

Up until quite recently, the notion of “dependency management” has (for the most part) been a foreign concept within the context of client-side, browser-based projects. The tide has swiftly turned, however, thanks in large part to the rapidly increasing popularity of Node, along with additional utilities built on top of it—a few of which this book has already covered (e.g., Grunt and Yeoman). These utilities have helped to bring desperately needed tooling and guidance to the untamed, “Wild West” that once was (and largely still is) client-side development.

In regard to dependency management, Bower has helped address this need by providing client-side developers with an easy-to-use mechanism for managing the various third-party libraries that applications rely on. For developers who are new to this concept and are not using client-side compilers such as Browserify, Bower has always been and continues to be a viable option for managing a project’s dependencies; however, as developers begin to see the advantages afforded by tools such as Browserify, Bower has begun to show signs of age. Furthermore, Bower is now almost defunct and is no longer under rapid development. As such, more and more developers are migrating away from Bower and turning toward alternative solutions, Browserify being one. Of course, Bower can still be used and is being used by many JS projects, but relying heavily on Bower is not something that is recommended.

At the beginning of this section, we mentioned that projects using Browserify are best thought of as client-side Node applications. In regard to dependency management, this statement is particularly important. Recall that during Browserify’s compile process, a project’s source code is scanned for calls to a global require() function. When found, these calls are executed within Node, and the returned value is subsequently made available to the client-side application. The important implication here is that when using Browserify, dependency management is significantly simplified when developers rely solely on npm, Node’s package manager. While technically, yes, it is possible to instruct Browserify on how to load packages installed by Bower, more often than not, it’s simply more trouble than it’s worth.

brfs

The brfs transform simplifies the process of loading file contents inline. It extends Browserify’s compilation process to search for calls to the fs.readFileSync() method . When found, the contents of the referenced file are immediately loaded and returned.

folderify

As in the previous example, the package.json file for this project has been modified to include folderify within its browserify.transform array. When compiled, Browserify will search for references to the include-folder module. When the function it returns is called, Browserify will load the contents of each file it finds within the specified folder and return them in the form of an object.

bulkify