Alameda, Bower and NPM integration in the CleverStyle Framework

In the previous article, you can learn how the framework works with statics, which comes with components created specifically for the framework.

At the same time, there are a huge number of third-party components in the form of Bower / NPM packages, the work with which the framework also simplifies and with which it integrates perfectly.

Alameda

Alameda is supplied for loading AMD modules with the framework. The framework alone takes care of generating the configuration for Alameda so that you can call the required modules simply by using the name of the module without the full path.

AMD modules for framework modules

Sorry for the tautology, but it sounds that way. AMD modules can be used, including in the framework modules, in order not to load unnecessary code on the pages before it is needed.

Here the following operations take place:

• for all modules of the framework with JavaScript files (the presence of the modules/*/assets/js directory is checked)
• an alias is created (the paths option of the Alameda configuration) for the module name and each functionality it provides

For example, for the MyModule module with meta.json :

 { "package" : "MyModule", "category" : "modules", ... "provide" : "my_feature", ... } 

Two aliases will be created:

• MyModule -> /modules/MyModule/assets/js
• my_feature -> /modules/MyModule/assets/js

If the AMD module is located on the path modules/MyModule/assets/js/my_module.js , then it can be called, for example, as my_feature/my_module . It is quite convenient if there are several alternative implementations of one AMD module, in which case the one that is installed will be used.

AMD modules in bower packages

The framework scans the contents of the bower_components directory in the root of the site and generates the Alameda configuration for each package found (the Alameda configuration packages option) of the following type:

 { "name" : "jquery", "main" : "dist/jquery", "location" : "/bower_components/jquery" } 

Generation of the package allows you to support not only modules from one file as jQuery, but also more complex configurations like lodash-amd , where you can load not the entire library, but only some of its parts (older versions of the framework were able to generate only aliases).

The name of the module is the name of the module, so jQuery can be used as jquery .

In order to understand which file to use in the main key, the key of the same name from bower.json (the first JavaScript file if an array of files is specified).

AMD modules in NPM packages

Similar to bower_components , the framework also analyzes the node_modules directory.

With package.json analysis, everything is more complicated, since many packages are primarily aimed at using Node.js in the environment.

In order to find a suitable file for use in a browser environment, the framework tries the following keys in package.json in order from higher priority to lower:

• browser
• jspm.main
• main

In the process of using, sometimes you have to do PR for packages that do not yet support this ( Redux , seamless-immutable ).

Bower / NPM packages as dependencies of the framework modules

For the framework, there is an optional Composer assets module, which allows you to declaratively indicate Bower / NPM dependencies for the framework modules in their meta.json keys require_bower and require_npm .

These dependencies will be installed for the corresponding module automatically, if this does not require access to the terminal on the server, or Node.js installed, and if there are conflicts, the installation of the module is interrupted, that is, the integration is complete.

It looks like this:

 { ... "require" : [ "System>=6.25", "System<7.0", "composer_assets" ], "require_npm" : { "qrcodejs" : { "version" : "1.0.0", "files" : [ "qrcode.js" ] } } } 

First, you need to specify the dependency on the composer_assets functionality, since it adds support for the necessary keys, without this, the framework does not understand what require_npm .

Secondly, you need to specify which module is needed and (optionally) which files need to be connected.
The fact is that by default, the framework considers packages as containing AMD modules and generates configurations for them similar to the above. But sometimes you need to connect a simple JavaScript file, a style file or a web component.

If only an AMD module is needed, the configuration can be simplified to the following:

 { ... "require_npm" : { "jquery" : "^3.0.0" } } 

One important point of integration is the support of aliases for packages installed via Composer assets along the paths bower_components and node_modules . In other words, jQuery from the last snippet can be obtained along the path /node_modules/jquery/dist/jquery.js , while the file is physically located along the path /storage/Composer/vendor/npm-assets/jquery/dist/jquery.js .

Production mode

If you enable static caching and compression in the framework settings, the files from {require_npm|require_bower}.*.files will be processed in the same way as the files supplied with the framework modules, so most of the supported optimizations will be applied here.

Also typical of many packages in the “wild” is the maintenance of the usual assembled modules with their minified versions (in bower.json and package.json , the usual ones are indicated). So in production, instead of dist/jquery.js will actually be loaded.

Custom version of Alameda

As it happens, unfortunately, quite often, the framework comes with customized builds of third-party projects, in this case with the custom version of Alameda.

The problem with the original is that in the "wild nature" there are some not quite correctly formed modules that Alameda refuses to support without the patch , the custom version can load and such modules which eliminates the manual configuration that would otherwise be required.

An example of such an incorrect, but now supported by the framework, module :

 define('inline-styles-formatter',[], function () { ... }); define('as-html-formatter',[], function () { ... }); define('scribe-plugin-inline-styles-to-elements',[ './inline-styles-formatter', './as-html-formatter' ], function ( inlineStylesFormatter, asHtmlFormatter ) { ... }); 

The discussion of the situation with the Alameda developer can be found here , and the fork with the necessary functionality here .

At last

As you can see, the framework integrates well with both the standard way of installing Bower / NPM packages, and supports them at the dependency level of the framework modules.

AMD package configurations are generated for the vast majority of properly designed packages completely automatically.

Always glad to new ideas and constructive comments.

» GitHub repository