require-local
Require-local is a wrapper for require() that allows referencing dependencies from the root of the local application
(or a sub-directory) instead of forcing the use of relative paths.
Though this is a somewhat controversial topic, I think that a reasonable argument can be made that relative pathing
for require() calls to modules local to an application, especially a large-scale app, can present a significant
maintenance burden and deter agressive refactoring. No one wants to edit hundreds of "../../" strings over dozens of
files just because they've decided to restructure their directory structure slightly. The argument to be made here is
that Node supports a non-relative pathing approach for third-party modules (in the form of "node_modules" being in the
require() search-path. The common response to this argument is "package it up and put it in your dependencies" but I
think this approach falls short. Frequently, modules are application-specific logic and would be meaningless outside of
the context of the application they were written for. Packaging something for reuse that will never be reused is the
epitome of over-engineering and a clear rejection of "do the simplest thing that will work".
Anyway, many people will argue that the require-local approach is bad practice. I'm not going to convince those people
that it's not (nor am I trying), but for those of you who think this is an oversight in Node, require-local provides a
fairly elegant (and ridiculously simple) implementation. The entire package is well under 10k, consists of maybe 20
lines of code, and has no external dependencies.
So enough with the arm-twisting. How does it work?
Quick Examples
var require_local = require('require-local');
var myModule = require_local('modules/myModule');
Where "myModule" is a module in the /modules directory of the application. For example:
//path/to/my/app/modules/myModule.js
You use the same code, regardless of where the source file lives in the directory structure of the application. No need
for "../../modules/myModule".
.root()
You can also chose to "pin" require-local to a sub-directory in your app using .root(), in which case require-local will
use specified sub-directory as the root directory for the require() path. So our above example would look like this:
var require_local = require('require-local').root('modules');
var myModule = require_local('myModule');
Require local can only be pinned to one directory so changing this changes it for everyone (the root path is held in a
closure for the function). This means that nothing in your app will be able to pin to a different root directory or
use require-local at the application's root path.
.globalize()
You can also choose to attached require_local to the global object in Node. I realize that this is another practice
that some would take issue with under the mantra of "global variables are bad" but it provides essentially identical
behavior to Node's require() (although require is actually local to the module so it's not really quite the same) and
is entirely optional. You don't have to use this facet of require-local and it doesn't behave this way by default.
To enable this functionality simply call .globalize() when you require the require-local module. This should be done
near the beginning of your main module and there's no need to assign the result to a variable because it will now be
attached to global.require_local.
require('require-local').globalize();
var myModule = require_local('modules/myModule');
Note that once you do this every module you load will have access to require_local so anyone can call it without having
to first require the require-local module. There's no harm in having sub-modules also call
require('require-local').globalize();
- if it's already there it doesn't do anything.
You can also supply .globalize() with an alternate name to use instead of require_local
. For example:
require('require-local').globalize('require$');
var myModule = require$('modules/myModule');
Note that you can only do this once and it can't later be changed. If you try you'll get an error thrown with the
message 'You cannot re-globalize require-local with a different name.'
An important note about the app root
Note that require-local uses the path to require.main.filename as the root of the application, so the assumption here
is that the main module is in the root of your application. If you're running as the main a module who's file lives
in a sub-directory in your app then everything will be relative to that that directory, NOT the app's root directory.