AngularJS & NodeJS Module Use - mikemilano/kalabox GitHub Wiki

AngularJS Modules

Kalabox organizes AngularJS files by sets of common functionality. For example, installer related controllers, services, and directives exist in the src/modules/installer directory. This is in contrast to seeds you may have seen where all controller files are organized in a controllers directory, services in a services directory, etc...

Simple module

If the module is not that complex, you can put configs, controllers, services, etc... into a single js file named src/modules/mymodule/mymodule.js.

Here's an example of a simple module with a unit test file.

.
└── src
    └── modules
        └── mymodule
            ├── mymodule.js
            └── test
                └── unit
                    └── mymodule.spec.js

In this example, the AngularJS module name as defined in angular.module() should be kalabox.mymodule.

Complex module

When a mymodule.js file gets complex, we encourage you to separate the logic into multiple files.

Examples of complex might be:

• The module is several hundreds of lines of code,
• There are several types of components in a single file (controllers, services, etc)

Here's an example of a more complex module with unit and e2e tests.

.
└── src
    └── modules
        └── mymodule
            ├── mymodule.controllers.js
            ├── mymodule.services.js
            └── test
                ├── e2e
                |  └── mymodule.spec.js
                └── unit
                    └── mymodule.controllers.spec.js
                    └── mymodule.services.spec.js

In this example, the AngularJS module names as defined in angular.module() should be kalabox.mymodule.controllers and kalabox.mymodule.services accordingly.

NodeJS Modules

External NodeJS modules are wrapped as AngularJS services so they can be injected and mocked for testing.

They should be defined as dependencies in package.json, and exposed as a services in src/modules/nodewrappers/nodewrappers.js. This provides for AngularJS friendly dependency injection, which gives us the ability to mock these services for testing.

Custom NodeJS Modules

Custom, Non-AngularJS NodeJS modules belong in the src/lib directory.

Generally, you should create your modular logic within the AngularJS module architecture, however, there are circumstances where it makes sense to create a custom NodeJS module. Ultimately it comes down to if the logic may be used outside the scope of AngularJS.

For example, the platform config module (src/lib/pconfig.js) is used to parse config/platform.js. It returns only config values to be used for the current platform. This is used for operations in grunt, as well as within the scope of the AngularJS application so it made sense to make it a NodeJS module.

For use in AngularJS, we wrap it as a service in the nodewrappers module, just as we do for external NodeJS modules.